Libris Britannia 4

home *** CD-ROM | disk | FTP | other *** search

/ Libris Britannia 4 / science library(b).zip / science library(b) / PROGRAMM / DB_CLIPP / H190.ZIP / VERTEX1.EXE / MANUAL < prev next >

Wrap

Text File | 1992-09-06 | 204KB | 5,106 lines

VVV VVV EEEEEEEEE RRRRRR TTTTTTTTT EEEEEEEEE XXX XXX VVV VVV EEEEEEEEE RRRRRRRR TTTTTTTTT EEEEEEEEE XXX XXX VVV VVV EEE RRR RRR TTT EEE XXX XXX VVV VVV EEE RRR RRR TTT EEE XXXXXX VVV VVV EEEEEE RRR RRR TTT EEEEEE XXXX VVV VVV EEEEEE RRRRRR TTT EEEEEE XXXX VVV VVV EEE RRR RRR TTT EEE XXXXXX VVV VVV EEE RRR RRR TTT EEE XXX XXX VVVVVV EEEEEEEEE RRR RRR TTT EEEEEEEEE XXX XXX VVVV EEEEEEEEE RRR RRR TTT EEEEEEEEE XXX XXX 000000 9999999 00000000 999999999 000 000 999 999 000 000 99999999999 000 000 999999999 000 000 999 000 000 99 999 00000000 ,,, 999 999 000000 ,,, 9999999 , Table of Contents Subject Page ___________________________________________________________________ General Information......................................... 2 Important Information....................................... 2 Overview............................................. 2 Parameters........................................... 2 Returnvalues......................................... 2 Examples............................................. 2 META Functions....................................... 2 Calling conventions.................................. 2 Copyright Information....................................... 2 Concept.............................................. 2 Blinker Link Script and Information......................... 2 Functions ............................................... 2 Array functions...................................... 2 ArBigArrElem()................................. 2 ArBldArr()..................................... 2 ARCOUNT()...................................... 2 AREVENOUT().................................... 2 ARMAX()........................................ 2 ARMAXPOS()..................................... 2 ARMIN()........................................ 2 ARMINPOS()..................................... 2 ARSHRINKARRAY()................................ 2 ARSMLARRELEM()................................. 2 ARSUM()........................................ 2 Box functions........................................ 2 BXBOX()........................................ 2 BXMAKEBOX().................................... 2 BXPUSHBUTTON()................................. 2 BXSCROLL()..................................... 2 BXUNBOX()...................................... 2 Database functions................................... 2 DBBIGFIELD()................................... 2 DBCONWORD().................................... 2 DBDELREC()..................................... 2 DBEXPDATA().................................... 2 DBFLDEXIST()................................... 2 DBFLDSUM()..................................... 2 DBIMPDATA().................................... 2 DBINUSE()...................................... 2 DBISDBF()...................................... 2 DBISMEMO()..................................... 2 DBJUMP()....................................... 2 Table of Contents Continued... Subject Page ___________________________________________________________________ Functions continued... Database Functions continued... DBLOOKFOR().................................... 3 DBSELDBVAL()................................... 3 DBSHRINKFILE()................................. 3 DBTBLVIEW().................................... 3 DBZAPDB()...................................... 3 Date functions....................................... 3 DTBEGEND()..................................... 3 DTBOM()........................................ 3 DTBOY()........................................ 3 DTCHKDTEFMT().................................. 3 DTDATEADD().................................... 3 DTDAYSIN()..................................... 3 DTDIFF()....................................... 3 DTDINM()....................................... 3 DTDOY()........................................ 3 DTDTOF()....................................... 3 DTDTOW()....................................... 3 DTSETDATE().................................... 3 DTWOY()........................................ 3 File functions....................................... 3 FIASKFILENAME()................................ 3 FIBLDDBF()..................................... 3 FIINFO()....................................... 3 FIKEEPVAR().................................... 3 FIMAKEUNIQUE()................................. 3 FITEMPCLEAN().................................. 3 FIVARGET()..................................... 3 Graphics functions................................... 3 GRBOX()........................................ 3 GRINIT()....................................... 3 GRLINE()....................................... 3 GRPTREAD()..................................... 3 GRPTWRITE().................................... 3 META functions....................................... 3 MFCOLORPICK().................................. 3 MFDATAENTRY().................................. 3 MFDBTOOLS().................................... 3 MFMAKEEXPR()................................... 3 MFPICKCOLOR().................................. 3 MFSELFILE().................................... 3 MFSETCOLOR()................................... 3 Table of Contents Continued... Subject Page ___________________________________________________________________ Functions continued... Menu functions....................................... 4 MNABORT()...................................... 4 MNALERT()...................................... 4 MNCHOICE()..................................... 4 MNFIELDS()..................................... 4 MNINFO()....................................... 4 MNMENU()....................................... 4 MNMESSYN()..................................... 4 MNMSG()........................................ 4 MNPULLDN()..................................... 4 MNTAKEFIELD().................................. 4 Math functions....................................... 4 MTARAVERAGE().................................. 4 MTARSUM()...................................... 4 MTDBAVERAGE().................................. 4 MTDBFLDSUM()................................... 4 MTDEC2HEX().................................... 4 MTHEX2DEC().................................... 4 Index functions...................................... 4 NXDBSEEK()..................................... 4 NXINDEXKEY()................................... 4 NXISVALID().................................... 4 NXSCAN()....................................... 4 NXSELECT()..................................... 4 Print functions...................................... 4 PROUTPUT()..................................... 4 String functions..................................... 4 STARRANGE().................................... 4 STBEGINSWITH()................................. 4 STCENTER()..................................... 4 STCHRINSTR()................................... 4 STCRUNCH()..................................... 4 STCUTLEFT().................................... 4 STCUTRIGHT()................................... 4 STENDSWITH()................................... 4 STLPAD()....................................... 4 STLSHIFT()..................................... 4 STRPAD()....................................... 4 STRSHIFT()..................................... 4 Table of Contents Continued... Subject Page ___________________________________________________________________ Functions continued... System functions..................................... 5 SYCHDIR()............................................ 5 SYCHDRIVE().......................................... 5 SYCOLDBOOT()......................................... 5 SYCURDRV()........................................... 5 SYDRIVE()............................................ 5 SYDRIVES()........................................... 5 SYDRVEFREE()......................................... 5 SYDRVETTL().......................................... 5 SYDRVROK()........................................... 5 SYDRVWOK()........................................... 5 SYMKDIR()............................................ 5 SYRMDIR()............................................ 5 Other functions...................................... 5 UTBELLATTN()......................................... 5 UTBELLDONE()......................................... 5 UTBELLERROR()........................................ 5 UTBELLUDF().......................................... 5 UTBITSET()........................................... 5 UTBYTEAND().......................................... 5 UTBYTEOR()........................................... 5 UTCHKCURSTYPE()...................................... 5 UTCOLCONVERT()....................................... 5 UTCTRLW()............................................ 5 UTDRIVES()........................................... 5 UTEDPIC()............................................ 5 UTENHANCED()......................................... 5 UTERRFUNCTION()...................................... 5 UTEXPRISTRUE()....................................... 5 UTGETCURSTYPE()...................................... 5 UTINIT()............................................. 5 UTISBIT()............................................ 5 UTKEEPVAR().......................................... 5 UTPROFILE().......................................... 5 UTSAVEKEY().......................................... 5 UTSTANDARD()......................................... 5 UTUNSELECTED()....................................... 5 Table of Contents Continued... Subject Page ___________________________________________________________________ Functions continued... Video functions...................................... 6 VIATT()........................................ 6 VICLS()........................................ 6 VICOLGRID().................................... 6 VIFADE()....................................... 6 VIGETMODE().................................... 6 VIISCGA()...................................... 6 VIISEGA()...................................... 6 VIISHERC()..................................... 6 VIISMCGA()..................................... 6 VIISMDA()...................................... 6 VIISVGA()...................................... 6 VIPRNT()....................................... 6 VISETMODE().................................... 6 VISLIDEOFF()................................... 6 GENERAL INFORMATION IMPORTANT: ---------- If You want to use ANY of the VERTEX Library functions, make sure You have called first of all the UTINIT() function to initialize important global variables. Not doing so may result in crashing Your program at any time. If You use BLINKER have a look first of all at the sample LINK script provided. It explains in some details what You have to look for in properly linking the lot. Since quite some functions are written in C or Assembler it is necessary to put the CCALL object into the ROOT should You decide to OVERLAY the Library. It also speeds up the program. C functions are marked with Ω Assembler functions are marked Σ CLIPPER functions are not marked Overview: --------- All functions listet are written in CLIPPER 5.01 and compiled with the latest CLIPPER compiler unless otherwise stated. Some CLIPPER functions call C- or Assembler functions. The functions are called with or without parameters as required. Parameters: ----------- To identify the type of parameters they are classed in different expressions of which the following list applies: <expCn> an expression made up of any valid characters <expLn> an expression of a logical value either .T. or .F. <expNn> an expression of a number being of type either FLOAT or INTEGER <expAn> an expression of an array of any type <expDn> an expression of a date <expOn> an expression of an object where in all cases the lower case "n" identifies the n-th number of the relevant expression passed. All parameter Idenifyers are enclosed in brackets. They may be <>, [] or () and can appear on their own or combined with each other. These symbols mean: ( ... ) PARAMETER LIST < ... > MUST be passed [< ... >] OPTIONAL, does not need to be passed The parameters my be divided by means of a comma (,) or a vertical line (|) which mean: , seperator of parameter, next to follow | seperator of two or more possible parameters Returnvalues: ------------- All functions returns something unless clearly identified as returning NIL or nothing. Examples: --------- As far as I could, I included some examples with each function description. They should give You some idea as to what You could/should do with them and how to call them. META functions: --------------- Several times, the term META functions is being used within this Library. A META function is a complete data processing- and manipulation function made up of several other functions of this Library, ready to be used and to be linked into programs. The use of these META functions enables one to create very quickly complex programs without the need for long development times Calling conventions: -------------------- All functions have a 2 character prefix identifying the group into which the function falls: Prefix Group __________________________________________________ AR Array manipulation- and creation BX Box manipulation- and creation DB Data manipulation- and creation DT Date manipulation FI File modifications GR Graphics functions MF General VERTEX META functions MN Menus and Dialog-boxes popup MT Math Functions NX Index manipulation PR Printer functions ST String manipulation SY low level System functions UT General Utilities VI General Video functions XX internal VERTEX Library functions IMPORTANT: Do not use the functions prefexed XX..... directly. They are powerfull C- and Assemblerfunctions and should ONLY be called by VERTEX functions. IMPORTANT COPYRIGHT INFORMATION ---------------------------------- This Library VERTEX is Copyright (c) 1991-92 by the Author W.A. Steinert, as well as all other accompanying documents and sample programs unless explicitly stated otherwise. Following concept applies to this package: 1. You may use, copy and distribute this package freely however You may NOT remove the Copyright Notice at the beginning of the program. You MUST mention the use of this Library in Your program and the associated documents. 2. You are encouraged to register this LIBRARY by sending a letter stating this wish to the author at following address: W.A. Steinert VERTEX Enterprises 27 Dahlemstr. 8750 Aschaffenburg West Germany 3. There is a small registration fee charged to private users for this VERTEX-Library, currently US $ 49.00. The user will receive a LIBRARY registered to him which will NOT include the COPYRIGHT notice at the beginning. 4. The author will inform registered users about any updates to the LIBRARY and will give them the opportunity to update for a fee of US $ 10.00, covering the mailing and packaging. Updates will be released about twice annually. This policy is valid for PRIVATE USERS only. The first update is free of charge for registered users. 5. Private, registerd users may order from the author for a fee of US $ 10.00 ( mailing and packaging ), a registered copy of the LIBRARY in following languages: FRENCH (released by 01/93 ) GERMAN ENGLISH ITALIAN ( released by 01/93 ) 6. Commercial users, Government offices and Companies must register the LIBRARY prior usage however they are granted the right to use the LIBRARY for not more than 60 days free of charge from the moment of receival of that LIBRARY. Any further usage of programs which have been compiled using this LIBRARY or the LIBRARY itself may continue only after registration of the VERTEX LIBRARY. The registration fee for NON-PRIVATE users is US $ 79.00. 7. NON-PRIVATE, NON-PROFIT Organisations are encouraged to register their LIBRARY with the author as they will receive a registered LIBRARY free of charge. They may use this Library ONLY for usage associated directly with the organisation. 8. Programs compile by using a NON-REGISTERED VERTEX Library may be sold without royalties however they MUST contain the Copyright Notice UNLESS these programs have been compiled by using a REGISTERED COPY OF THE VERTEX LIBRARY. 9. The author shall not be liable for any direct, indirect, incidental or consequential damages resulting or seemingly result from the use, test or distribution of the Library and/or the accompanying programs. 10. The use of this Library constitutes agreement to the preceeding points as well as to the proposition that by such You become bound to the terms of this agreement. CLIPPER is a Trademark of NANTUCKET Corporation and Computer Associates International Inc. Turbo Assembler is a copyright by BORLAND INTL. Microsoft C is a copyright by MICROSOFT Corp. SAMPLE BLINKER LINK SCRIPT -------------------------- # # Blinker 1.50 Sample Link file for Clipper 5.01 using VERTEX # Library # # This sample script is intended to be used as a template for your # own scripts # # This script is set up a a development script, that enables # incremental linking, and overlays EXTEND.LIB from the Nantucket # libraries. When incremental linking is enabled, applications # will use somewhat more memory than normal, due to a certain # amount of 'padding' being left at the end of each Clipper # procedure, but this is offset by the extremely fast incremental # link times. # # Before shipping a completed application, you should disable the # incremental linking feature, which will save memory, and increase # execution speed by: # # a) Enabling the 5.01 Clipper paging system # b) Remove the padding between procedures # c) Turning on symbol table compression # # For final links - UN-COMMENT the following command: # #BLINKER INCREMENTAL OFF #DEBUG # # If You have troubles with Your application after linking it with # Blinker (i.e. termiates with Memory faults ) try increasing the # OPSIZE.... # # Burn in your own Clipper variables here eg: F25;SWAPPATHC:\; # BLINKER EXECUTABLE CLIPPER F25;E1024;X64;BADCACHE; # # Specify the EXE filename here: # OUTPUT MYFILE # # List your Clipper S'87 object modules here. The first FILE # mentioned in any Blinker link script MUST be a Clipper code # module. The first module may be overlaid if required. # FILE MYTEST # # Uncomment if You want to use the profiler. Call the function # UTPROFILE() as second function ( right after UTINIT() ) and run # Your programming in profiling mode to find out where to put Your # Modules. # MODULE UTINIT #MODULE UTPROFIL # # Uncomment the next lot to increase output speed of anything which # has to do with GETS or Buttons. # #MODULE UTEDPIC # # clippers own global maxcol and maxrow function..... MODULE __GTMAXCOL MODULE __GTMAXROW #MODULE __ATPROMPT #MODULE BXMAKEBOX #MODULE EXITSTATE #MODULE READVAR #MODULE SUBSCRIPT #MODULE _EXITSTATE #MODULE GETACTIVE #MODULE SETTLE #MODULE AFILL #MODULE BXBUTTON # # Uncomment and list your 3rd party non overlayable object modules # here eg: OVERLAY's RESIDENT.OBJ # #FILE <3rd party1>,<3rd party2> BEGINAREA # #List the rest of your Clipper code files here. # #FILE <next Clipper file> # ..... # #UNCOMMENT and list your own Clipper code libraries here # # #UNCOMMENT and list your overlayable 3rd party libraries here #as well as the VERTEX Library # #Allocates the VERTEX US-Library # ALLOCATE VERTEXUS # ALLOCATE <3rd party> ENDAREA # # UNCOMMENT and list 3rd party non-overlayable libraries here: # VERTEX Root Module has to be here. #LIB <3rd party> LIB VERTROOT # # If you want the 5.01 debugger UN-COMMENT the following: # NOTE: The 5.01 debugger library MUST be specified as a FILE # # FILE CLD.LIB # # UNCOMMENT for dLESKO's FUNCky 1.5 library # #@FUNCKY50.LNK # # Call the distribution script to overlay EXTEND.LIB # or substitute for LIB EXTEND.LIB # @CL501MIN.LNK # # Microsoft LLIBCA C 6.00 library comes last if needed. # #LIB LLIBCA IMPORTANT ARRAY FUNCTION INFORMATION ------------------------------------ I have tried to put some usefull array handling functions together which might come handy for You. All arrayfunctions are written entirely in CLIPPER 5.01 as most other functions are and make full use of CLIPPERS new features inclusive codeblocks. Whereever possible I have included some examples in the functiondescription so You have some idea how to use them. Try them out, You can't break anything. ArBigArrElem() ============== Function: ArBigArrElem( <expA> ) --> integer Synopsis: Checks an array and returns the length of the longest array-element. Useful for knowing the longest element when used in conjunction with arrays containing different types of elements or when used in conjunction with ACHOICE() to define correct display if the maximum width of the box is not known. Samples: lArray :={ "short",; "little longer",; "very long display string" } llongest := ArBigArrElem( lArray ) ltop := 0 lleft := 0 lbottom := 10 lright := lleft + 1 + llongest lChoice := ACHOICE( ltop, lleft, lbottom,; lright, lArray ) Result: an ACHOICE box where all elements are visible in their entire length. Notes: Works on arrays of all types AND mixed types. Trailing spaces in CHARACTER arrays are NOT counted, leading spaces ARE counted. If the array contains a codeblock, the function returns 0 as codeblocks are not a selectable item in themselves and should only be called via the EVAL() function. Returns: length of the longest array element or 0 if Type is other than C,N,L,D or M. ArBldArr() ========== Function: ArBldArr( <expN1>, <expC1> ) --> array of strings Synopsis: Builds an array from a delimited string Fills an array with a colon delimited string of the form "John:Willy:Ralph:Eddy". The colon [:] is the delimiter. The size of the array is set by the parameter <expN1>. If the number of elements defined is less than the actual amount of parameters in the colon delimited string, only the amount of defined elements are being created in the array and the rest discarded. <expN1> Number of elements <expC1> Colon delimited string of elements Example: lunch:= {} lunch := ARBLDARR( 3,"Pizzas:Chickens:Burgers" ) Returns: Array containing the values passed ARCOUNT() ========= Function: ARCOUNT( <expA>, <expC> ) --> integer Synopsis: Counts exact matches of TYPES in array. <expA> Array to be searched. <expC> value of any type to be searched for in array Examples: lFields := DBSTRUCT() AEVAL( lFields, { | x | AADD( lFldTypes,; x[ DBS_TYPE ] ) } ) lNbrOfChar := ARCOUNT( lFldTypes, "C" ) && counts C fields lNbrOfNum := ARCOUNT( lFldTypes, "N" ) && counts N fields lNbrOfDate := ARCOUNT( lFldTypes, "D" ) && counts D fields lNbrOfLogic := ARCOUNT( lFldTypes, "L" ) && counts L fields lNbrOfMemo := ARCOUNT( lFldTypes, "M" ) && counts M fields lNbrOfMemo := ARCOUNT( lFldTypes, NIL ) && counts NIL fields Returns: number of matches found 0 if no matches found. AREVENOUT() =========== Function: AREVENOUT( <expA1>, <expN1> ) --> array Synopsis: Expands array elements to even length. <expA1> array to expand <expN1> width to expand each element to This function will expand each array element to a given length. I have used it to achieve an even pushbutton menu by expanding all elements to the biggest in the array. N.B. You may also shorten all elements to e specified length. Examples: oldarray := { "tiny",; "short",; "much longer" } newarray := AREVENOUT( oldarray, 15 ) ##------ the new array looks like this ------ ## "tiny " "short " "much longer " All elements are now 15 characters long Returns: the new array ARMAX() ======= Function: ArMax( <expA1>, [<expN1>, <expN2>] ) --> integer|float Synopsis: Finds the largest number in a NUMERICAL array. <expA1> a numerical array [<expN1>, <expN2>] optional starting and ending position for search defaults to 1 and last Examples: lNumbers := { 10,2789,1,0,9567 } lLargest := ARMax( lNumbers ) && lLargest = 9567 lLargest := ARMax( lNumbers, 1, 4 ) && lLargest = 2789 Notes: <expN1> must always be smaller than <expN2> and mustn't be 0. Returns: If <expN1> is less than 1 or larger than <expN2>, the function will return NIL. Also if <expN1> is less than 1 or <expN2> is larger than the array. Otherwise returns the largest number. ARMAXPOS() ========== Function: ARMAXPOS( <expA1> ) --> integer Synopsis: Finds the position of the greatest number within an array. <expA1> numeric array to search. Examples: lArray := { 1, 2067, 1077, 10, 5987 } lPos := ARMAXPOS( lArray )&& lPos will contain 5 Returns: an integer identifying the position of the greatest number within the passed array returns 0 if an error occured. ARMIN() ======= Function: ArMin(<expA1>,[<expN1>,<expN2>]) --> integer|float|NIL Synopsis: Finds the smallest number in a NUMERICAL array. <expA1> a numerical array [<expN1>, <expN2>] optional starting and ending position for search defaults to 1 and last Examples: lNumbers := { 10,2789,1,0,9567 } lSmallest := ARMin( lNumbers ) && lSmallest = 0 lSmallest := ARMin( lNumbers, 1, 3 ) && lSmallest = 1 Notes: <expN1> must always be smaller than <expN2> and mustn't be 0. Returns: If <expN1> is less than 1 or larger than <expN2>, the function will return NIL. Also if <expN1> is less than 1 or <expN2> is larger than the array. Otherwise returns the smallest number. ARMINPOS() ========== Function: ARMINPOS( <expA1> ) --> integer Synopsis: Finds the position of the smallest number within an array. <expA1> numeric array to search. Examples: lArray := { 2, 2067, 1077, 10, 5987 } lPos := ARMINPOS( lArray )&& lPos will contain 1 Returns: an integer identifying the position of the smallest number within the passed array returns 0 if an error occured. ARSHRINKARRAY() =============== Function: ArShrinkArray( <expA>, <exp?> ) --> Array Synopsis: This Function searches an array for a given expression and deletes this expression of the array, however leaving NO NIL elements in the array where the found expression was, effectively shrinking the array by the amount of found expressions. <expA> a single dimension array <exp?> an expression of any kind Note: The passed expression <exp?> may NOT be an array and the passed array <expA> may ONLY be a single dimension array i.e.: test := { 0,3,NIL,4 } ShrinkArray(test,0) ... returns an array containing { 3, NIL, 4 } not like the CLIPPER Function ADEL() which would leave the array at the same size with a trailing NIL element. Returns: an array without passed expression <exp?> ARSMLARRELEM() ============== Function: ArSmlArrElem( <expA> ) --> integer Synopsis: Checks an array and returns the length of the smallest array-element. Useful for knowing the shortest element when used in conjunction with arrays containing different types of elements. Samples: lArray := { "short",; "little longer",; "very long display string" } lshortest := ArSmlArrElem( lArray ) Notes: Works on arrays of all types AND mixed types. Trailing spaces in CHARACTER arrays are NOT counted, leading spaces ARE counted. If the array contains a codeblock, the function returns 0 as codeblock are not a selectable item in themselves and should only be called via the EVAL() function. Returns: length of the shortest array element or 0 if Type is other than C,N,L,D or M . ARSUM() ======= Function: ARSUM( <expA1> ) --> float Synopsis: Sums all numeric elements of an array. <expA1> numerical array to sum Examples: lArray := { 10, 11, 1, 2 } lTotal := ARSUM( lArray ) && lTotal contains 24 Returns: a float containing the sum of the array passed, on Error NIL IMPORTANT BOX FUNCTION INFORMATION ================================== The box functions in general make use of some very fast C and Assembler functions which I have not listed at present ( there is really no need for it ). You should be able to make full use of them even without knowing that there are any C or Assembler functions behind all this. These C and Assembler functions are well behaved and can all be overlayed ( at least I had no problems sofar ). All box functions make use wherever possible of all TEXT modes of Your video card. However I am unable to test the functions on all cards available, so if there is a problem with a specific card, let me know what card You have and what the problem is. I try to include the fixup in the next releases. Remember, licensing the Library will guarantee You a bug-fix before the next release, free of charge! IMPORTANT: ---------- All BX.... functions make heavy use of ROM BIOS function calls and use the IBM character set to draw the boxes. If You decide to switch Your Graphics card into GRAPHICS MODE remember that all characters will be display exclusive OR'd (XOR) with the current display contents. They make no use of the attributes You may pass. Thats why the frame around boxes displayed in Graphics mode on an empty black screen will have ALLWAYS black as background color. I have been using BLINKER 1.51 for putting together the sample programs and I think RTLINK or WARPLINK should be able to handle them just as well. BXBOX() ======= Function: BXBOX(<expN1>..<expN4>,[<expN5>],[<expN6>],[<expN7>], [<expN8>], [<expN9>] ) --> logical Synopsis: Pops a Box on given coordinates <expN1>..<expN4> Box coordinates on screen [<expN5>] Boxtype as identified below... [<expN6>] attribute of Box [<expN7>] shadow position [<expN8>] shadow foreground color [<expN9>] shadow background color [<expC1>] user defined character for boxframe Boxtype definition for <expN5> being -1 to 15: Box Type Bottom Right Top Left ------------------------------------------- -1 (----) - - - - 0 (0000) S S S S 1 (0001) S S S D 2 (0010) S S D S 3 (0011) S S D D 4 (0100) S D S S 5 (0101) S D S D 6 (0110) S D D S 7 (0111) S D D D 8 (1000) D S S S 9 (1001) D S S D 10 (1010) D S D S 11 (1011) D S D D 12 (1100) D D S S 13 (1101) D D S D 14 (1110) D D D S 15 (1111) D D D D If a box type is chosen from this table, corner characters will be automatically chosen to match the sides. -1 will allow user defineable box character to be used. Notes: Works best in TEXT modes only as You are unable to use attributes to display characters. As these box drawing functions are done with characters, they will use colors only. Returns: .T. if successfully created, otherwise .F. BXPUSHBUTTON() ============== Function: BxPushButton( <expN1> .. <expN3>, <expA1>, [<expL1>] ) --> integer Synopsis: Sets up a number of HORIZONTAL or VERTICAL pushbuttons and waits for user input. <expN1>..<expN2> row/column coordinates of pushbottons. <expN3> button number to be used to start off with. <expA1> array of strings defining the buttons. [<expL1>] defines if buttons are displayed horizontal (.T.) or vertical (.F.) defaults to .T. The function selects the first character of each string defined in <expA1> as a shortcut key so selection may be done either by using the first character of each string or the cursor control keys and ENTER. Colors used are in accord with the current SETCOLOR() settings. This function is a low level function and used by all boxes which require user input. I have left it out for use in other ways i.e. so you can create your own boxes with user response. Examples: lStart := 1 lChoices := { "YES","MAYBE","NO" } lSelected := bxhpushbutton( 10, 20, lStart,lChoices ) DO CASE CASE lSelected == 1 && yes .... your code ... CASE lSelected == 2 && maybe .... CASE lSelected == 3 && no .... ENDCASE Returns: an integer identifying the selected choice, otherwise 0 BXMAKEBOX() =========== Function: BXMAKEBOX( <expN1>..<expN4>,[expC],[expN5] ) --> string Synopsis: Draws a shadow box on the screen at given coordinates and saves the underlying screen area as well as the current colorsettings. <expN1>..<exp4> Screen coordinates of the box to be drawn. The coordinates DO NOT include the drop shadow. These are automatically included, so make sure you have enough space for them. The shadow is 1 extra character position depending upon the placing of the shadow. <expC> an optional colorstring or color variable for the popup box. <expN5> an optional number defining the shadow position. You can determine the Shadow position on hand of the numeric keypad on the Keyboard: 7 = top left 9 = top right 1 = bottom left 3 = bottom right 0 = no shadow Examples: lScrSave := BXMAKEBOX(5,5,10,10) * draws a box at 5,5,10,10. Color is as defined by SETCOLOR() * shadow position is based on C_SHADPOS. lScrSave := BXMAKEBOX(5,5,10,10,C_POPCOL) * draws a box at 5,5,10,10. Color is C_POPCOL. * shadow position is based on C_SHADPOS. lScrSave := BXMAKEBOX(5,5,10,10,C_POPCOL,9) * draws a box at 5,5,10,10. Color is as defined * by SETCOLOR() shadow position is 9 (upper right * hand corner) Notes: Do not use the CLIPPER Function RESTSCREEN() to restore saved screenareas which are stored in the string returned by the BXMAKEBOX() function. Use the provided BXUNBOX() function instead. If You use this function in Graphics mode, remember that You can't use attributes to display characters. In Graphics mode characters are displayed with COLOR, not ATTRIBUTES. Returns: a string containing the coordinates, colorsettings and underlying screenarea. BXSCROLL() ========== Function: BXSCROLL( <expN1> .. <expN7> ) --> logical Synopsis: Scroll area of given box-coordinates <expN1> number of lines to scroll ( 0 clears the area within the parameters <expN3> to <expN6>. <expN2> attribute to use for scroll <expN3> .. <expN6> area coordinates to scroll ( top, left, bottom, right ) <expN7> direction to scroll ( 1 = up, 0 = down ) This function will scroll a given area within a box either up or down using a given attribute. It scrolls the area a number of lines. Returns: .T. if successful, otherwise .F. BXUNBOX() ========= Function: BXUNBOX( <expC> ) Synopsis: Removes a box which was previously created by the function BXMAKEBOX() <expC> Saved screen string created by BXMAKEBOX() Examples: lScrSave := BXMAKEBOX( top, left, bottom, right ) ... your code ... && lScrSave contains the saved && screen ................. BXUNBOX( lScrSave ) Notes: Do not use with any other saved screen string than the one created by the BXMAKEBOX() function. Returns: Nothing IMPORTANT DATABASE FUNCTION INFORMATION ======================================= There are a lot of extra DB functions NANTUCKET did not supply so I have tried to close the gap a little. Some of the DB Functions should really be classed as META functions ( where do You draw the line? ), but I left them here. All DB Functions make extensive use of codeblocks so they should be rather fast. Whereever I could I also made use of lots of CLIPPERS Objects, especially the TBROWSE objects as You may find in the DBTBLVIEW() function. DBBIGFIELD() ============ Function: DBBigField( <expC> ) --> integer Synopsis: Checks a database and finds the length of the longest field within that database. <expC> the ALIAS or the NAME of the database to search This is a very useful funtion if you don't know the length of the fields within a database and you want to display the contents of a database on the screen. Use this function to find out how long the longest Field is. Checks if the database is in use and searches it. Opens the database if not in use in the next lower unoccupied workarea and searches it. Examples: lDbase := "MYDATA" llongfield := DbBigField( lDbase ) Result: "llongfield" contains a numeric value specifying the length of the longest field. Returns: an integer specifying the length of the longest field in the database ( this is NOT the length of the fieldname ) DBCONWORD() =========== Function: DbConWord( <expC>, <expL> ) --> logical Synopsis: Function converts a CLIPPER or DBase File into a MS-WORD Datafile, that is, it actually copies the Data into a newly created MS-WORD Datafile. Requires a database to be in use in the current workarea. <expC> contains the Filename of the MS-WORD Datafile to be createt. <expL> logical expression denotes if erased records are to be copied (.F.) or not (.T.). Defaults to (.T.) ... that is - erased records are NOT copied. Returns: .T. if successfully transfered, .F. on error. DBDELREC() ========== Function: DBDELREC( [<expC>], [<expN>] ) --> integer Synopsis: Pops up a dialog box to allow deletion or recalling of the current record. The prompt in the box depends upon the current status of the record. If the record is currently deleted, the prompts will be: Un-Delete No Action otherwise Delete No Action [<expC>] optional box colorstring defaults to C_POPCOL [<expN>] optional shadowposition defaults to C_SHADPOS Examples: lWhatHappened := DBDELREC() Returns: 1 if record was deleted -1 if record was restored 0 if nothing happened DBEXPDATA() =========== Function: DbExpData( [<expC>], [<expN1>], [<expN2>, <expN3>] --> NIL Synopsis: This function gives the user a choice of exporting a set of data previously defined. The function works on the current workarea and exports ALL UNDELETED records found. To export only part of the data, create a temporary database and use the function on it. [<expC>] optional box color string defaults to C_POPCOL [<expN1>] optional shadow defaults to C_SHADPOS [<expN2>..<expN3>] optional top/left coordinates of box defaults center. Currently supported export formats are: DBASE III plus SDF ASCII delimited MS-WORD Datafile others are in preperation. During the operation a box is being presented showing the progress by displaying the amount of records still to be processed. Note: a workarea and database must be in use before this function is called. Examples: USE EXPDB DBEXPDATA() - or - DBEXPDATA( Color, Shadow, top, Left ) Returns: Nothing DBFLDEXIST() ============ Function: DBFLDEXIST( <expC1>, <expC2> ) --> logical Synopsis: Checks if Field exist in Database. The function will check if a given fieldname exist in a sepcified database. <expC1> database to search for field <expC2> fieldname to search for Examples: ? DBFLDEXIST( "MYDBASE.DBF", "NAMES" ) && prints .T. if "NAMES" exist in "MYDBASE.DBF" Returns: .T. if field exists; otherwise .F. DBIMPDATA() =========== Function: DbImpData( [<expC>], [<expN1>], [<expN2>, <expN3>] ) --> NIL Synopsis: This function gives the user a choice of importing a set of data. The function works on the current workarea and imports ALL data of the given file. [<expC>] optional box color string defaults to C_POPCOL [<expN1>] optional shadow defaults to C_SHADPOS [<expN2>..<expN3>] optional top/left coordinates of box defaults center. Currently supported import formats are: DBASE III plus SDF ASCII delimited During the operation a box is being presented showing the progress by displaying the amount of records imported. Note: a workarea and database must be in use before this function is called. Examples: USE EXPDB DBIMPDATA() - or - DBIMPDATA( Color, Shadow, top, Left ) Returns: Nothing DBINUSE() ========= Function: DbInUse( <expC1>, [<expN1>] ) --> Workarea Synopsis: Searches undestructive in all Workareas if the ALIAS passed in <expC> is already in Use. <expC1> Alias to be searched for. [<expN1>] optional starting workarea. Notes: The Function will terminate as soon as the first ALIAS was found. Returns: Workarea if ALIAS was found, 0 if ALIAS was not found. DBISDBF() ========= Function: DBISDBF( <expC1> ) --> logical Synopsis: Checks if Database is valid DBASE format. The function tests the database in question by trying to open it. On success, the database will be closed and the old settings reinstated - returning .T.; on error the function will reset the old settings and return .F.; That the function doesn't crash is made possible by means of the VERTEX Error handling function. Examples: lisvalid := dbisdbf( "SAMPLE.DBF" ) && lisvalid contains .T. if valid database Returns: .T. if database is valid and not corrupted otherwise .F. DBISMEMO() ========== Function: BISMEMO() --> logical Synopsis: Checks if there exists a MEMO-field for a database. Examples: DBISMEMO() - or - ALIAS->( DBISMEMO() ) Returns: .T. if there exists a memofield for the database; otherwise .F. DBJUMP() ======== Function: DBJUMP() --> string Synopsis: Pops up available, open Databases for selection. The function searches all possible workareas for open databases and pops up a selection of available databases. The user may select a database which will become then the current database. Examples: USE customer USE addresses DBJUMP() && pops a selection of && CUSTOMER and ADDRESSES && allowing the user to change && the workarea to any of them Returns: the alias of the selected workarea if changed successful, otherwise the alias of the current workarea. DBLOOKFOR() =========== Function: DbLookFor( <expC1> ) --> Alias Synopsis: Searches a database for records fitting a search- expression. <expC1> Search expression which must evaluate to a logical value It searches the Database of the current Workarea and will write the Recordnumber of the found Records in a temporary File. Filename: TMP#####.##$ where # is a numeric value Structure: Fieldname -> FOUNDREC Fieldtype -> NUMERIC Fieldlength ->10 ALIAS: RECFOUND Recordnumbers are written in logical order of any found records. If any records have been found the Alias of the temporary Database will be passed, otherwise an empty String is passed. Notes: Apart from type-checking of the passed parameter and the amount of parameters passed, no other check is done. An incorrect expression results in an error. Best use the function MFMAKEEXPR() to create interactively a VALID expression. The Database for the found records is opened in EXCLUSIVE mode in the next available lowest workarea and remains opened. If a call to this function has been done previously, the same workarea will be used, all previously found records dropped and a new set created. Processes the database in its natural order unless Indexes are in use. In this case the Index-order is used. NETWORK USERS: Be aware that this functions does not lock the found records in any way. This means that other users may delete the found records after the function terminates and you are not aware of this - thus it may lead to an erroneous result. Returns: Alias of database where found recordnumbers are listed for further processing DBSELDBVAL() ============ Function: DbSelDbVal( <expC1>, <expN1>..<expN4>, [<expC2>], [<expC3>] ) --> Fieldvalue Synopsis: A function which returns a fieldvalue from a database chosen by a user. <expC1> a valid fieldname of a database in use in the current workarea. <expN1>..<expN4> valid coordinates of the window in which a selection of fieldvalues appears. [<expC2>] an optional parameter used as header of the window. [<expC3>] optional displaycolor string [<expN4>] optional shadow position The window will be created and a selection of fieldvalues will appear. The order of the values depends upon the index currently in use or natural order if no index is in use. A highlight bar is used to scan the values by means of the Cursor control keys as well as PgUP and PgDN. This function requires the used database to be opened in shared modus. Notes: The fieldwidth will be adjusted to the size of the window. It means that fieldvalues larger than the window will be truncated to fit the window. This is of particular interest for NUMERIC fields since the number displayed may not be the correct number: e.g. +------+ |123456|7890 <-- a numeric field, 10 digits + | | a window, 6 digits wide = +------+ a displayed number of first 6 digits although only part of the fieldvalue is being displayed, the complete fieldvalue will be returned. Make sure that the window for numeric fields wide enough to allow the user to select the right number. The fieldname passed must be a valid fieldname for the database in use. No parameter checking is done apart from correct type. Return: fieldvalue if successful empty string if not DBSHRINKFILE() ============== Function: DBShrinkFile() --> logical Synopsis: Packs a Database and updates associated indexes. Requires an open database in the current workarea. All open Indexes will be updated during the packing process: Notes: Database will be locked during packing process. Returns: .T. if packing process was successful, .F. if aborted or unsuccessful of whatever reason. These reasons could be: 1) Database not opened before functioncall 2) Database could not be locked and user terminates function. DBTBLVIEW() =========== Function: DBTBLVIEW(<expC1>,[<expC2>,<expN1>..<expN4>],[<expL1>]) --> logical Synopsis: A tabular Database editor/viewer based upon CLIPPERS TBROWSE objects. You may call this function if You don't like the blockformat of datamanipulation. It does basically the same as DBDATAENTRY() however at present there are some functions not available with this Tabelviewer as there are with DBDATAENTRY(). <expC1> a databasename to work on ( this is NOT the ALIAS ) [<expC2>] an optional index to be active while working with the database [<expN1>.. <expN4>] optional display parameters of the Table defaults to 3,3,MAXROW()-3,MAXCOL()-3 [<expL1>] optional logical to allow table editing, .T. edits, .F. does allow only browse; defaults to .F. Returns: .T. Data was worked on, all ok.,; .F. Parameter error DBFLDSUM() ========== Function: DBFLDSUM( <expC1>|<expN1> ) --> float Synopsis: Sum a Field of a database currently in use. The function is adding up all values of a database field either passed by NAME or FIELDPOSITION. <expC1> name of databasefield to sum <expN1> fieldposition of databasefield to sum Examples: USE ACCOUNTS lTotal := DBFLDSUM( 2 ) - or - lTotal := DBFLDSUM( "PAYMENT" ) both do the same and return the same value. Returns: a float number representing the TOTAL of the Field, 0 on error. DBZAPDB() ========= Function: DbZapDb() --> logical Synopsis: Zaps a database, indexes and all memofields currently in use The Function takes care of Network locking itself. Examples: USE CUSTOMER INDEX SNAME lResult := DBZAP() && lResult contains .T. if zapping was && successful. Index SNAME is also zapped Returns: .T. if successful .F. if unsuccessful for whatever reason IMPORTANT DATE FUNCTION INFORMATION =================================== CLIPPER somehow neglected the DATE functionality and if You need some DATE Functions.... well here they are. For the Date calculations, all DATE Functions will temporarily change the DATE to ANSI standard, do the calculations and then switch back to whatever DATEFORMAT You choose to run Your system on. I found this the most reliable way of calculating DATES so one knows where the DAYS and the MONTHS etc. are... DTDATEADD() =========== Function: DTDATEADD( <expD>, <expN1>, <expN2> ) --> Date Synopsis: Adds or subtracts days, weeks, months or years to/from a given date. <expD> date to work on <expN1> a positive or negative integer to add or subtract from date <expD> <expN2> action as defined in VERTEX.CH: DT_DAY= add days DT_WEEK = add weeks DT_MONTH = add months DT_YEAR = add years Examples: DTDATEADD( DATE(), 5, DT_DAY ) && adds 5 days DTDATEADD( DATE(), -5, DT_DAY ) && subtract 5 days DTDATEADD( DATE(), 5, DT_MONTH ) && DTs 5 months DTDATEADD( DATE(), -5, DT_MONTH ) && subtract 5 months Notes: If the number <expN1> is of a positive value, it will be added to the date in <expD>; if the number <expN1> is of a negative value, it will be subtracted. The function takes care itself of leapyears. Returns: a date as result of the operation, NIL if wrong parameters were passed DTBEGEND() ========== Function: DTBEGEND( <expD>, <expN1>, <expN2>, [<expN3>] ) --> Date Synopsis: Determines begin or end of week, month or quarter <expD> Date to examine <expN1> Beginning ( WEEK_BEGIN ) or End ( WEEK_END ) of ... <expN2> Week ( OF_WEEK ), or Month ( OF_MONTH ), or Quarter ( OF_QUARTER ) in which... input Date <expD> falls. WEEK_BEGIN, WEEK_END, OF_WEEK, OF_MONTH, OF_QUARTER are Macros defined in VERTEX.CH Options: If week, <expN3> is day of the week beginning or end of the week <expN1> falls on, with sunday being 1 and saturday being 7. Examples: cdate := ctod("01/15/90") bow:= DTBEGEND( cdate, WEEK_BEGIN, OF_WEEK, 1 ) && beg of week eow:= DTBEGEND( cdate, WEEK_END, OF_WEEK, 7 ) && end of week bom:= DTBEGEND( cdate, WEEK_BEGIN, OF_MONTH ) && beg of month eow:= DTBEGEND( cdate, WEEK_END, OF_MONTH ) && end of month boq:= DTBEGEND( cdate, WEEK_BEGIN, OF_QUARTER ) && beg of quarter eoq:= DTBEGEND( cdate, WEEK_END, OF_QUARTER ) && end of quarter Returns: a date depending upon the action done DTBOM() ======= Function: DTBOM( [<expD>] ) --> date Synopsis: Calculates the beginning of the month date. [<expD>] optional date defaults to current date. Examples: lStartDate := DTBOM( CTOD( "10/15/90" ) ) && lStartDate will contain 10/01/90 Returns: Beginning DATE of the MONTH in which the passed parameter falls; NIL if invalid parameter is passed. DTBOY() ======= Function: DTBOY( [<expD>] ) --> date Synopsis: Calculates the beginning of the year a given date falls in. [<expD>] optional date defaults to current date. Examples: lStartYear := DTBOY( CTOD( "10/15/90" ) ) && lStartYear will contain 01/01/90 Returns: Beginning DATE of the YEAR in which the passed parameter falls; NIL if invalid parameter is passed. DTCHKDTEFMT() ============= Function: DtChkDteFmt( <expC> ) --> array Synopsis: Accepts a dateformat string and checks its validity. <expC1> Date formatstring as used by the SET() function Comparison is done according to the country specific date formats as defined in CLIPPER when using the SET( _SET_DATEFORMAT ) function. country identifiers as defined by CLIPPER: 1 = AMERICAN 2 = ANSI 3 = BRITISH 4 = FRENCH 5 = GERMAN 6 = ITALIAN 7 = JAPAN 8 = USA Returns: an array with 2 elements element[1]contains .T. if dateformat was correct, otherwise .F. element[2]contains the country identifier as defined by CLIPPER if dateformat was correct, otherwise 0 DTDAYSIN() ========== Function: DTDAYSIN( <expD> ) --> integer Synopsis: Calculates number of days in a month <expD> a date which is used to calculate the number of dates in the month the date is falling in. Examples: ? DAYSIN( CTOD( "02/29/1992" ) ) && prints the number 29 Returns: an integer representing the number of days of the month a passed Date falls into. 0 if an error occured. DTDIFF() ======== Function: DTDIFF( <expD1>, <expD2>, <expN> ) --> integer Synopsis: calculates the difference between two given dates depending upon action chosen. <expD1> start date <expD2> end date <expN> action as defined in VERTEX.CH: DT_DAY= in days DT_WEEK = in weeks DT_MONTH = in months DT_YEAR = in years Examples: lDate1 := CTOD( "10/15/90" ) lDate2 := CTOD( "10/26/90" ) diffdays := DTDIFF(adate,adate2, DT_DAY) diffweeks := DTDIFF(adate,adate2, DT_WEEK) diffmonth := DTDIFF(adate,adate2, DT_MONTH) diffyears := DTDIFF(adate,adate2, DT_YEAR) Returns: integer representing the difference of both dates depending upon action chosen. DTDINM() ======== Function: DTDINM( [<expD>] ) --> integer Synopsis: Calculates number of days in month of given date. [<expD>] optional date defaults to DATE() This function also takes consideration of Leap Years. Examples: DTDINM( CTOD( "10/20/89" ) ) returns 31 Returns: an integer representing the amount of days in the month of parameter or current date. DTDTOF() ======== Function: DTDTOF() --> string Synopsis: Returns the current Date-Format string The function returns the current date setting as a format string 8 characters OR 6 characters long, unlike CLIPPERS DTOS() function which will always return a string YYYYMMDD. Examples: SET DATE TO ANSI lFormat := DTDTOF() && lFormat contains the string "yyyy.mm.dd" if century && is set on, otherwise it contains "yy.mm.dd" Returns: a date format string according to the current setting DTDTOW() ======== Function: DTDTOW( [<expD>] ) --> string Synopsis: Converts a date to a sentence. The Function convertes a given date to a sentence. [<expD>] optional date defaults to DATE() Examples: DTDTOW( CTOD( "12/10/90" ) ) && returns "December 10th, 1990" DTDTOW( CTOD( "12/01/90" ) ) && returns "December 01st, 1990" DTDTOW( CTOD( "12/03/90" ) ) && returns "December 03rd, 1990" Returns: a string containing a date converted to a sentence if correct date was passed; otherwise an empty string DTDOY() ======= Function: DTDOY( <expD> ) --> integer Synopsis: Calculates the day-of-year from a given date. <expD> a date defaults to current date Examples: DTDOY( CTOD("03/17/92") )&& returns 77 Returns: an integer DTSETDATE() =========== Function: DTSETDATE( [<expN1>]|[<expC1>] ) --> string Synopsis: Sets a date to a defined date format [<expN1>]|[<expC1>] numeric or string value identifying the wanted date format When using a numeric value, keep in mind that only the following values are correct: 1 = AMERICAN 2 = ANSI 3 = BRITISH 4 = FRENCH 5 = GERMAN 6 = ITALIAN 7 = JAPAN 8 = USA The string values have been pre-defined in the headerfile VERTEX.CH and may used as follows _AMERICAN _ANSI _BRITISH _FRENCH _GERMAN _ITALIAN _JAPAN _USA You may also define Your own dateformat however keep in mind that it should be somehow in the format: dd:mm:yy if century is set OFF or dd:mm:yyyy if century is set ON The delimiters are being used the way You have defined them. Notes: If CENTURY is set ON and You post a dateformat showing no century information, the function will not post your date. The same goes if You set CENTRY OFF and want to post a dateformat which includes century information. Returns: the current dateformat if new dateformat was posted successfully, otherwise empty string DTWOY() ======= Function: DTWOY( [<expD>] ) --> integer Synopsis: Calculates the week-of-year from a given date. [<expD>] a date defaults to current date Examples: DTWOY( CTOD("11/04/91") )&& returns 45 Returns: an integer IMPORTANT FILE FUNCTION INFORMATION =================================== Not much to say about the FILE functions except again, all Functions are written in CLIPPER 5.01 ( unless otherwise marked ) and not in beefed up SUMMER '87 ( pardon the pun ). Although the SUMMER '87 compiler was quite good for its time, there were important features missing which had to be programmed in a round about way ( I think all CLIPPER pro's agree with me ). Now the 5.01 version does a better job. FIASKFILENAME() =============== Function: FiAskFilename( [<expC>], [<expN1>],; [<expN2>..<expN3>] ) --> string Synopsis: Asks the user for a filename. The function checks the validity of the fielname to comply with DOS. The Function Key F2 allows the user to create a valid, unique Filename. Warns the user if filename alreay exists. [<expC>] optional box colorstring defaults to c_popcol [<expN1>] optional box shadow position defaults to c_shadpos [<expN2>..<expN3>] optional box coordinates default to screen center. Examples: FIASKFILENAME() returns a valid Filename Notes: The function DOES NOT CREATE A FILE, it supplies only the filename. Returns: a string containing a valid filename. FIBLDDBF() ========== Function: FiBldDbf( <expC1>,<expC2>|<expA> ) Synopsis: Creates a DBF from a delimited string <expC1> name of DBF to create <expC2> long string delimited ... Fields must be delimited with colons, the Field elements with commas --- or --- <expA> an array of Fields and Field elements delimited with commatas Examples: when <expC2> is a string... FiBldDbf( "CUSTOMER","FNAME,C,30:ADDR,C,; 30:ZIP,N,10:CREDIT,L" ) && creates a database called CUSTOMER with 4 Fields && FNAME... Type C, Length 30 && ADDR ... Type C, Length 30 && ZIP ... Type N, Length 10 && CREDIT ... Type L, Length 1 when <expA> is used... lDbStruc := { "FNAME,C,30",; "ADDR,C,30",; "ZIP,N,10",; "CREDIT,L" } FiBldDbf( "CUSTOMER", lDbStruc ) does the same. Notes: FiBldDbf() expects an unused area to work in, and will return .f. if it detects a DBF open in the current area. An overwrite will not be allowed. Returns: .T. if database created successfully otherwise .F. FIINFO() ======== Function: FIINFO( <expC>, <expN> ) --> string Synopsis: Examines a file and returns fileinfo based upon passed parameters. <expC> filename of file to check <expN> what to look for. These options are defined in the VERTEXUS.CH file and are as follows: FI_SIZE FI_DATE FI_TIME FI_ATTR Examples: filesize = fileinfo("customer.dbf", FI_SIZE) && filesize contains the size of file "customer.dbf" && as a string Returns: a string of the wanted fileinfo FIKEEPVAR() =========== Function: FiKeepVar( <expC1> ) --> Filename Synopsis: Writes <expC1> to disk and returns a unique Filename. <expC1> a string of any kind. This Function is very useful in writing saved screen variables to disk for keeping them there for the duration of the program so they may be recalled at a later time. Allows saving quite some Memory. MEMO Fields may be exported into a file for editing with an external editor. Just remember to erase the Files. Do this by using the function fitempclean() as last functioncall in your program. Examples: lScrSave := SAVESCREEN( 0,0,20,50 ) lFilename := FiKeepVar( lScrSave ) && lFilename contains a unique filename where && the SAVESCREEN string was written to... - or - lFilename := FiKeepVar( "this string is"+; " written to disk" ) Returns: Filename if successfully saved, otherwise empty string FIMAKEUNIQUE() ============== Function: FiMakeUnique( [<expC1>] ) --> Filename Synopsis: Creates a unique Filename. Checks if Filename already exists and changes Filename accordingly. <expC1> optional extension If the optional extension is used the Filename construct is: TMP#####.___ where the underscores ( ___ ) in the Filename are replaced by the extension. Otherwise the filename defaults to the Filename Construct: TMP#####.##$ where # denotes an integer in the range 0 .. 9 Notes: Use only valid extension characters for the filename as no checking on validity is done. Returns: a unique filename not existing in default directory. FITEMPCLEAN() ============= Function: FiTempClean() --> NIL Synopsis: Erases all temporary files createt by the user. Requires the PUBLIC array c_tfiles to be available where the names of all temporary files are stored in, e.g. with Function fikeepvar() DBLOOKFOR() Notes: Erases only the temporary files created by a specific user all others are left unchanged. Call this function as the very last thing you do before leaving a program since it will erase also the files in which evtl. Screen areas have been saved, e.g. with Functions: DBLOOKFOR() fikeepvar() etc. Also, use the fitempclean() function only if these above functions had been used previously or you wrote manually to the array c_tfiles. Returns: Nothing FIVARGET() ========== Function: FiVarGet( <expC1> ) --> variable Synopsis: Reads a temporary file in which a variable was saved. <expC1> contains the filename into which the variable was previously save with the function FIKEEPVAR() Notice: make sure that saved screen variable was read back correctly otherwise may corrupt display. Returns: Saved screen if successfully read, otherwise NULL value IMPORTANT GRAPHICS FUNCTION INFORMATION ======================================= I have supplied a view Graphics functions as a start. In general You do not need to link anything special in to use them. However be aware that You do need a Graphics Video Adapter to use these functions. Also, You must switch into a Graphics mode to be able to see the output and BEFORE your use any graphics functions. CLIPPERS ? and ?? functions don't work in Graphics mode as well as the DEBUGGER. I will try and expand the Graphics Library a little in time to give You more possibilities and will improve all functions so that You may use them in both TEXT and GRAPHICS modes. GRBOX() ======= Function: GRBOX( <expN1>..<expN5> ) --> integer Synopsis: Draws a Graphics box on screen The function will draw a box on a screen in graphics mode a the given coordinates and returns the sum of a pixels drawn. <expN1> TOP LEFT X coordinate <expN2> TOP LEFT Y coordinate <expN3> BOTTOM RIGHT X coordinate <expN4> BOTTOM RIGHT Y coordinate <expN5> COLOR of box Examples: GRBOX( 100,100,600,400,3 ) Notes: Remember You are in graphics mode so all coordinates are in PIXELS and NOT IN COLUMNS AND ROWS. In general: standard CGA has 320 x 200 standard EGA has 640 x 350 and standard VGA has 640 x 480 pixels. Returns: integer, number of pixels drawn; 0 on error GRINIT() ======== Function: GRINIT( <expN1>, <expN2> ) --> NIL Synopsis: Sets maximal X,Y coordinates for Graphics Screens Call this function whenever You want to set the maximal x,y screen coordinates to any other values than the ones set by the UTINIT() function. The globals b_maxx and b_maxy are set according to what Your system allows at maximum. If Your video card supports 800 x 600 pixels, call this function with: GRINIT( 800, 600 ) setting the maximal x,y coordinates to this value to benefit from the provided Graphics functions Examples: GRINIT( 800,600 ) && set maximal x,y coordinates && to 800x600 GRINIT( 640,480 ) && " " " 640x480 Returns: Nothing GRLINE() ======== Function: GRLINE( <expN1> .. <expN5> ) --> integer Synopsis: Draw a colored line in Graphics mode. <expN1> starting X coordinate <expN2> starting Y coordinate <expN3> ending X coordinate <expN4> ending Y coordinate <expN5> color of line The function will draw a line on the current display page from starting X,Y coordinates to ending X,Y coordinates in the specified color. Notes: If starting X,Y and ending X,Y are the same coordinates only one pixel is plotted. Returns: integer; the number of actual pixels plotted. GRPTREAD() ========== Function: GRPTREAD( <expN1>, <expN2> ) --> integer Synopsis: Reads a colored pixel at X,Y coordinate and returns the palette color at a given point <expN1> X coordinate of the point whose color to read and return <expN2> Y coordinate Examples: lColor = GRPTREAD( 600, 300 ) && reads color at position 600,300 and && returns a numerical color Returns: integer GRPTWRITE() =========== Function: GRPTWRITE( <expN1> .. <expN3> ) --> NIL Synopsis: Writes a colored pixel at X,Y coordinate <expN1> X coordinate <expN2> Y coordinate <expN3> color of pixel The function will write a "colored" pixel at a given X,Y coordinate. Notes: Make sure that the pixel is within the bounds of the valid Screenarea ( see b_maxx and b_maxy coordinates ) which You set with UTINIT() to default values or using the GRINIT() function do specifiy Your own. Examples: GRPTWRITE( 100,200,3 ) Returns: Nothing IMPORTANT META FUNCTION INFORMATION =================================== The META Functions are something special in many ways. I have them included for the beginners ( or the overworked experts ) to have a way to quickly put together a program with all needed features to satisfy the customer. A META Function is a function which may stand on itself and supply a complete set of functionality to the user ( i.e. the MFDATAENTRY() function ) and could quite well be a program on its own. Use them if You want to, but be aware that they take away some space. MFCOLORPICK() ============= Function: MFCOLORPICK() --> NIL Synopsis: A meta-function allowing the selection of colors from a list The Function gives the user the option via a menu to select at present 12 pre-defined color combinations which will be saved in the file SYSTEM.DAT Colors will be initialised with the SETCOLOR() function Returns: Nothing MFDBTOOLS() =========== Function: MfDbTools( <expN1>,<expN2>,[<expA1>],[<expN3>],; [<expC2>],[<expL2>]) --> NIL Synopsis: A Database Toolbox containing major database handling functions. These functions can be disabled for use by means of the third parameter which requires an array of logical values. <expN1> Coordinate, top row of toolbox window <expN2> Coordinate, left side of toolbox window [<expA1>] optional array of logical values denoting if item is selectable or not: ( .T. = selectable ) ( .F. = not selectable ) defaults to ALL selectable. [<expN3>] optional parameter of windows shadow [<expC2>] optional parameter of window color [<expL2>] optional parameter for display windows with or w/o frame Following functions are available with this toolbox: 1. Export data (in part or whole ) 2. Import data 3. Shrink database ( removes deleted records ) 4. Jump database ( selects new working database) 5. Zap database ( removes ALL data from database ) 6. Interactive build index and set if desired 7. Print selected records Examples: MFDBTOOLS( 5,5,{.T.,.T.,.T.,.T.,.T.,.T.,.T.} ) && pops up the tools and all being enabled MFDBTOOLS( 5,5 ) && the same.... Returns: Nothing MFDATAENTRY() ============= Function: MfDataEntry( [<expA1> .. <expA3>] ) --> NIL Synopsis: Allows generic Data-manipulation. Requires an open database and three passed arrays. If no parameters are passed, then defaults to all fields being displayed and the FIELDNAMES being the field descriptors. No indexes are then being used. <expA1> an array containing the Database- Structure of the database currently in use. Use the function DBSTRUCT() to get the required info about the structure, e.g. lStruct := DBSTRUCT() and pass the array "lStruct" as first param. <expA2> an array of field descriptors of the current Database. <expA3> an array of logical values. Any .T. value results in the field being displayed, .F. prevents the field being displayed. Example: USE sample lStruc := DBSTRUCT() && Structure lFields := {"Field1","Field2","Field3"} && Fielddescriptors lYN := { .T., .F., .T. } && display ? YES/NO lNtx := { "NAME","ACCOUNT" } && 2 indexes are used MfDataEntry( lStruc, lFields, lYN, lNtx ) && functioncall Results in FIELDS "Field1" and "Field3" being displayed and possible to be edited. "Field2" will not appear. USE sample MfDataEntry() Results in ALL fields being displayed with their FIELDNAMES being the descriptors. Notice: All Functionkeys in the range F1 - F10 being SET with the SETKEY() CLIPPER Function will be saved and returned to their former settings. Requires a database in use in the current workarea Returns: Nothing MFMAKEEXPR() ============ Function: MfMakeExpr( <expA>, [<expC1>], [<expN1>] ) --> Expression Synopsis: Allows the interactive creation of an expression. This expression can be used to find certain data in a database, which matches the expression. An array of fieldnames must be passed. There is no checking if the fieldnames passed, fit the database in use. So make sure that the database is in use of which the fieldnames have been passed in the array <expA> <expC1> optional colorstring <expN1> optional shadowposition The screen will be build in a fashion of: +--box1-------+ +--box2------+ +--box3------+ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | +------------+ +------------+ | | +--box4---------------------+ | | | | | | | | +-------------+ +---------------------------+ where the boxes 1 to 4 following options contain: Box1: all fields selectable by the user. Box2: operator used for the comparison Box3: operand used for the comparison, which can be a) a value already existing in the database b) a new value to be entered by the user. alternatively contains .T. or .F. option when selecting a field of type LOGICAL. Box4: the spot where the new value can be entered. Note that box 4 is only relevant if the selected field is NOT of type "L" (logic). Fields of type "M" (Memo) cannot be included in the expression. Returns: a valid expression if completed, an empty string if unsuccessful MFPICKCOLOR() ============= Function: MfPickColor() --> logical value Synopsis: pops up a selection of color-choices and stores it to file SYSTEM.DAT Returns: .T. if succesfully changed; .F. if no changes were made MFSELFILE() =========== Function: MfSelfile( [<expC>] ) --> string Synopsis: A META function for selecting a PATH/File. Pops up a window in the center of the screen allowing the user to select either a file, or change a directory permanently. [<expC>] optional three character extension to search for. Possible extensions currently are: ALL DBF NTX FRM SDF ASC others will be added soon. I have tried to put something together the quick way for Your convenience to change a directory and select a file. I know it's not the ideal thing but please be free to make suggestions. A row of buttons on the right side allow You to select the type of files You want to see or select in the left window. Choose the Filetype, then choose the file. Push the "RETURN" button to have the full filename ( w/o the path returned ). Examples: lFile := MFSELFILE() && to return a filename lFile := MFSELFILE( "DBF" ) && allows selection && of DBF files && ONLY. Other options && such as && DIR change etc. are not && affected Returns: a string containing the filename MFSETCOLOR() ============ Function: MFSETCOLOR() --> NIL Synopsis: Development Tool for finding color combinations. Sets the global color- and display type variables. Several global (public) color variables are used by the functions. These are: c_normcol - For normal input/output c_normmenu - For normal 'menu to' operations c_popcol - For popup box colors c_popmenu - For popup box menus c_errcol - For popup error boxes c_frame - Frame string c_shadatt - Shadow color attribute (numeric) c_shadpos - Shadow position (0,1,3,7,9) c_xplode - Logical - explode windows? All are of the format "f/b,f/b,,,f/b" (f- foreground b-background) MFSETCOLOR() allows interactive setting of these colors. The variables are stored in SYSTEM.DAT - which is created if needed by MFSETCOLOR(). If SYSTEM.DAT is not present, UTINIT() will initialise a default set of colors, otherwise it will restore from SYSTEM.DAT Notes: MFSETCOLOR() does not effect the current color setting. It manipulates SYSTEM.DAT. To utilize colors selected by MFSETCOLOR(), a restore from SYSTEM.DAT must be done. Returns: Nothing IMPORTANT MENU FUNCTION INFORMATION =================================== The Menu functions make use of other VERTEX-functions as well as several low level C and Assembler functions. They are fast, small and easy to use. Currently I have stayed away from SAA type menus as I found them using quite some memory and processing overhead. MNABORT() ========= Function: MNABORT( [<expC>], [<expN1>..<expN2>] ) --> logical Synopsis: Pops up a dialog box asking the user "ABORT?" and allows to make a choice if an escape key ( ASCII 27 ) was pressed at a wait state. <expC> optional characterstring of the box color defaults to the globaly defined POPMENU color <expN1> .. <expN2> optional box position where: expN1 is the equivalent of TOP ROW and expN2 is the equivalent of LEFT COLUMN Example: INKEY(0) IF MNABORT() EXIT ENDIF Returns: .T. for yes; .F. for no MNALERT() ========= Function: MNALERT( <expC1>, <expA1> ) --> integer Synopsis: A popup dialog-box with more than 2 choices displayed centered. <expC1> Expression to be displayed as question. <expA1> answers Examples: lChoice := mnalert( "Are you ready", 10, 10,; { "Yes!", "Not yet", "Almost" } ) DO CASE CASE lChoice == 1 && yes ... your code ... CASE lChoice == 2 && not yet ... your code ... CASE lChoice == 3 && almost ... your code ... OTHERWISE && ESC ENDCASE Returns: an integer identifying the selected option; 0 on error or if no selection MNCHOICE() ========== Function: MNCHOICE( <expA>, <expN1>..<expN4>, [<expC1>],; [<expL>], [<expC2>], [<expN5>] ) --> integer Synopsis: The equivalent of CLIPPER's ACHOICE() function however it also creates a box for it with an optional heading and restores the underlying screen after selection. <expA> an array of choices. <expN1>..<expN4> location of choice box. [<expC1>] optional boxtitle [<expL>] optional execute flag defaults to .F. - if set to .T., this function will execute a return on a first letter match. [<expC2>] optional boxcolor defaults to C_POPCOL [<expN5>] optional boxshadow position defaults to C_SHADPOS Examples: MyArray := { "Apples", "Pears", "Bananas" } lChoice := MNCHOICE( MyArray,Top,Left,Bottom,Right,; "Fruits",.T.) Returns: an integer identifying the selected array element. 0 for no selection MNFIELDS() ========== Function: MNFIELDS( [<expC1>],[<expN1>..<expN4>], [<expL>], [<expC2>],[<expN5>] ) --> string|integer Synopsis: pops up a box to allow selection of fields of current database. [<expC1>] optional title of box. [<expN1>..<expN4>] optional box coordinates default to screen center. [<expL>] optional returnvalue selector. If set to .T. returns selected FIELDNAME, if set to .F. returns the FIELDPOSITION of the selected field; defaults to .T. [<expC2>] optional box colorstring defaults to c_popcol [<expN5>] optional box shadowposition defaults to c_shadpos Notes: Do not confuse this function with the MNTAKEFIELD() function. MNFIELDS() examines the current database and returns the fieldname or the fieldposition depending upon the 5th parameter set, whereas MNTAKEFIELD() relies upon the fieldnames passed as an array and does not need an open database. Returns: if parameter 5 is set to .T. --> selected fieldname if parameter 5 is set to .F. --> FIELDPOSITION within current database of selected Field MNINFO() ======== Function: MNINFO( <expC1>,<expN1>,<expA1> ) --> string Synopsis: Displays a popup box with up to as many lines of a messages, that fit on the screen, NOT waiting for a Keypress. The amount that will fit on the screen will be calculated out of: maximum number of displayable rows - 6 The maximum width that will be displayed is: maximum number of displayable columns - 6 The message remains until removed with UNBOX() <expC1> message box color string defaults to C_POPCOL <expN1> position of the box-shadow defaults to C_SHADPOS <expA1> an array of messages Examples: MNMSG(,,{ "An error has been detected!" }) MNMSG(,,{ "A","B","C","D","E","F" }) Notes: The message is centered on screen in a box. Returns: underlying screen in string. Nothing on error. MNMENU() Function: MNMENU( <expC1>..<expC3>,[<expC4>..<expC16>]) --> integer Synopsis: A vertical popup menu in a centered box using <expC1> as title and performing a MENU TO ... on <expC2> to <expC16> where <expC1> may be passed as empty string for a popup menu w/out a title. Examples: lChoice := mnmenu("Selection","Edit","Add",; "Delete","Quit") Returns: an integer representing the position of the selected item. 0 (zero) of nothing was selected. MNMSG() ======= Function: MNMSG(<expC1>,<expN1>,<expC2>|<expN2>,; [<expC3>..<expC10>]) --> NIL Synopsis: Displays a popup box with up to 9 lines of a message, waiting then for a Keypress or optionally a time-out. <expC1> message box color string defaults to C_POPCOL <expN1> message box shadow position defaults to 3 (bottom right ) <expC2>|<expN1> a message string or a numeric value. If this parameter is a messagestring, than the message will be displayed as the first message line within the message box; however if this parameter is of a numeric value, than the function will see it as the optional timeout value after which the box will be automatically removed from the screen - otherwise the box will remain until a further key is pressed. [<exp3>..<expC10>] optional further message strings. Examples: MNMSG(,,"An error has been detected!") MNMSG(,,"A","B","C","D","E","F") MNMSG(,,5,"A","B","C","D","E","F") && removed && after 5 seconds Notes: The message is centered on screen in a box. Once the message is displayed, the function waits for a keypress and then removes the window, restoring screen underneath, or waits for time-out value defined as 3rd parameter. Returns: Nothing MNMESSYN() ========== Function: MNMESSYN( <expC1>, [<expC2>,<expC3>] ) --> logical Synopsis: A popup YESNO dialog-box. <expC1> Expression to be displayed as question. [<expC2>,<expC3>] optional answers defaults to YES/NO Examples: if messyn("Are you ready") if messyn("Are you ready","Not Yet","Almost") Returns: .T. if first answer (leftmost) was selected, .F. if right answer (rightmost) was selected. MNPULLDN() ========== Function: MNPULLDN( <expN1>, <expA1>..<expA3> ) --> float Synopsis: Pulldown Menu creator and handler. Draws a pulldown menu with up to 8 menu boxes. selection process starts with position passed with <expN1>. <expN1> a floating point number representing the start of the menu process, i.e. 1.01 starts with 1st Menu, 1st Menu option <expA1> .. <expA3> three arrays <expA1> each element defines the Menu. A Menu definition is a String delimited with colons for each Menuoption. Example: "TITLE:option:option:option..." with up to 99 options per string. <expA2> is a box definition array. It is 7 elements long and defines the following: Element: 1. <expL> Draw top bar box? T/F 2. <expC> Top bar color 3. <expC> Menu Box color 4. <expC> Menu Box frame 5. <expN> Menu Box shadow position (0,1,3,7,9) 6. <expN> Menu Box shadow attribute 7. <expN> Row to start menu bar <expA3> is an array of title column positions to override the internal 'figerin algorithm. Examples: #include "vertex.ch" Box := { "Datafiles:Use Datafile",; "Indices:Select Indices:Index order",; "Editing:Field Replacement:Tabular Edit",; "Reporting:Build Query:Print Lists",; "Other:List text file:Change Directory",; "Quit" } BoxSel := 1.01 BoxData := { .T.,; && draw the top bar box "W/B,GR/R,,,W/N",; && top bar color string "W/B,N/R,,,W/N",; && drop box color VERTEX_SSSS,; && drop box frame 3,; && drop box shadowposition 8,; && drop box shadowattribute 0 } && row # of menu bar DO WHILE .T. BoxSel := MNPULLDN( BoxSel, Box, BoxData ) DO CASE case BoxSel == 1.01 && Datafiles -> Use... ....... case BoxSel == 2.01 && Indices -> Select... case BoxSel == 2.02 && Indices -> Index order... case BoxSel == 3.01 case BoxSel == 5.01 ENDCASE ENDDO Passing a menu array element with title only will result in no menu box, with the title being the only selection and returning a selection value of <MENU>.1. (i.e. a 'Quit' box) Warnings: It takes some work to start all options and titles with a first letter that is unique so that first letter selection may take place. Returns: float number to identify relative position of chosen menu-option where the whole numerical part identifies the master menu and the fraction the sub menu. MNTAKEFIELD() ============= Function: MnTakeField( <expA>,[<expN1>..<expN4>],[<expC>], [<expN5>], [<expL>]) --> Fieldname Synopsis: Accepts an Array of Fieldnames and displays it for serselection at coordinates <expN1> to <expN4>. <expA> array of fieldnames [<expN1>..<expN4>] optional coordinates of box default is center [<expC>] optional box colorstring defaults to C_POPCOL [<expN5>] optional box shadow position defaults to C_SHADPOS [<expL>] optional execute flag defaults to .F. - if set to .T., this function will execute a return on a first letter match. Examples: lFields := { "Name", "Address", "City" } lChoice := MNTAKEFIELD( lFields,top,left,bott,right ) - or - lFields := { "Name", "Address", "City" } lChoice := MNTAKEFIELD( lFields, top, left, bott, right,; M->color, M->shadow, .T.) Returns: FIELDNAME if one was chosen, Empty string if none was chosen. IMPORTANT MATH FUNCTION INFORMATION =================================== The Math functions provided are using wherever available a Math- Coprocessor. Some functions are however simply adding elements which make use of codeblocks to speed up the adding process. These however don't use a Co-Processor. Functions which are using a Co-Processor (whenever there is one available) have been identified as such. MTARAVERAGE() ============= Function: MTARAVERAGE( <expA1> ) --> float Synopsis: Gets the average of all numbers in an array. There can be any types of elements within the array as the function only calculates the average of elements which are of type NUMERIC. <expA1> the array to scan Examples: lArray := { "just for fun", 12, 200, 11.6, 97.12, .T. } lResult := MTARAVERAGE( lArray ) && lResult contains 80.18 as average Returns: a float containing the average of all NUMERIC elements 0 if no NUMERIC elements found or on Error. MTARSUM() ========= Function: MTARSUM( <expA1> ) --> float Synopsis: Sums a numeric array. <expA1> numerical array to sum Examples: lArray := { 10, 11, 1, 2 } lTotal := MTARSUM( lArray ) && lTotal contains 24 Returns: a float containing the sum of the array passed, on Error NIL MTDBAVERAGE() ============= Function: MTDBAVERAGE( <expC1>|<expN1>, <expN2> ) --> float Synopsis: Gets the average of all numbers in a Field identified by <expC1> or <expN1>. Expects an open database in the current Workarea. <expC1> the name of the field to average or <expN1> the fieldnumber to average <expN2> Type 0 = averages all records incl. deleted, Type 1 = averages only deleted records, Type 2 = averages all BUT deleted records. Examples: lResult := MTDBAVERAGE( 1, 0 ) && lResult contains the average of Field 1 && ALL records lResult := MTDBAVERAGE( "INCOME", 1 ) && lResult contains the average of the Field && "INCOME" only deleted records lResult := MTDBAVERAGE( "PAYMENTS", 2 ) && lResult contains the average of the Field && "INCOME" all BUT deleted records Returns: a float containing the average of the Field 0 if no values in Database or on Error. MTDBFLDSUM() ============ Function: MTDBFLDSUM( <expC1>|<expN1> ) --> float Synopsis: Sum a Field of a database currently in use. The function is adding up all values of a database field either identified by NAME or FIELDPOSITION. <expC1> name of databasefield to sum <expN1> fieldposition of databasefield to sum Examples: USE ACCOUNTS lTotal := MTDBFLDSUM( 2 ) - or - lTotal := MTDBFLDSUM( "PAYMENT" ) both do the same and return the same value. Returns: a float number representing the TOTAL of the Field. 0 on error MTDEC2HEX() =========== Function: MTDEC2HEX( <expN1> ) --> string Synopsis: Converts an Integer into a hexadecimal string. The function accepts an integer and converts it into a hexadecimal string . <expN1> Integer to convert Returns: a string representing the integer, empty string if wrong parameter was passed. MTHEX2DEC() =========== Function: MTHEX2DEC( <expC1> ) --> integer Synopsis: Converts hexadecimal string into an Integer. The function accepts a hexadecimal string and converts it into an integer. <expC1> hexadecimal string to convert Notes: Don't pass the "H" which usually is used to identify a HEX number. Examples: MTHEX2DEC( "29" ) && returns 41 MTHEX2DEC( "29h" ) && returns NIL MTHEX2DEC( "A0A" ) && returns 2570 Returns: an integer equivalent of the hexadecimal string, NIL if wrong parameter was passed. IMPORTANT INDEX FUNCTION INFORMATION ==================================== The Indexfunctions are primarily used to provide an easy interface to create and handle CLIPPER and DBASE indexes. Some functions have the functionality of META functions and give the user quite some control over the happenings. NXISVALID() =========== Function: NXisvalid( <expC> ) --> logical Synopsis: Checks if index-expression is valid for database in current workarea Requires an open Database in the current workarea. Returns: .T. if index-expression is valid, otherwise .F. NXINDEXKEY() ============ Function: NXINDEXKEY( <expC>, <expN> ) --> string Synopsis: Extracts the key-expression of an index. Is sensitive to DBase III or Clipper generated indexes. <expC> name of index <expN> index type. There are two different types of indexes ( sofar ) usable with CLIPPER: Type1 = CLIPPER NTX format Type2 = DBase III NDX format Returns: index key-expression if sucessfully read, empty string if no expression found, i.e. invalid file NXSCAN() ======== Function: Nxscan( [<expC>] ) --> array Synopsis: Scans a workarea for indexes. [<expC>] optional workarea name defaults to current workarea. a workarea is scanned for open indexes. If a workarea is passed as parameter, it will be scanned for all open indexes, otherwise the current workarea will be scanned. All open indexes are written into an array. Examples: allindexes := {} allindexes := nxscan( ALIAS() ) && scans current && workarea -or- allindex := nxscan() && scans current workarea -or- allindex := nxscan( "NEWAREA" ) && scans workarea && "NEWAREA" -or- AREA := "OTHERS" allindex := nxscan( AREA ) && scans workarea "OTHERS" Returns: array containing open indexes empty array if no index found NXDBSEEK() ========== Function: NxDbSeek( [<expL>] ) --> integer Synopsis: Seeks a record in the current workarea. [<expL>] optional setting for Softseek on or off; defaults to .F. where: .F. = SOFTSEEK OFF .T. = SOFTSEEK ON The function will seek a record in the current workarea using the controlling index. Depending upon the Indexkey, the user is required to enter values of the fields containedin the index and in the sequence appearing in the Index. Notes: Softseek is used, irrespective of overall settings, according to [<expL>]. Examples: INDEX ON SURNAME+FNAME TO NAMES SET INDEX TO NAMES lRecFound := NxDBSeek( .T. ) && seeks a record using the index "NAMES" - Softseek && is set ON - the function requests input for FIELDS && SURNAME and FNAME Returns: a recordnumber if SEEK was successful, otherwise 0 NXSELECT() ========== Function: NxSelect( [<expN1>], [<expC>], [<expN2>] ) --> logical Synopsis: Allows the setting of indexes in the current workarea [<expN1>] a numeric value of the controlling index ( 0 - 15 ) where 0 sets the controlling index off so that the database can be accessed in its natural order. [<expC>] optional colorsetting of selection box default to c_popcol [<expN2>] option box-shadow position default to c_shadpos if the parameter <expN> is not passed, then the function will scan the current workarea for open indexes and allows interactive setting of the controlling index. Notes: Requires an open database in the current workarea Examples: NxSelect( 2 ) && sets indexorder to 2 - or - NxSelect() && pops up a choice of available indexes && and allows interactive setting of the && indexorder Returns: .T. if successful; .F. if unsuccessful IMPORTANT PRINT FUNCTION INFORMATION ==================================== The provided printfunctions give You support in printing records of a database by making use of existing QUERY sets created with the MFMAKEEXPR() function. PROUTPUT() ========== Function: PROutput( <expC> | <expA> ) --> NIL Synopsis: Prints the contents of a database while using a report form passed as parameter <expC>. Requires an open database in the current workarea. To use this function best, copy first of all the records You want to have included in the report into a seperate database and use it temporarily. This is the faster way of selecting records You want to print. The function will than give You a progressing report by means of a counter on how many records still to go. <expC> name of reportform to be used. If the DOS extender .FRM is not being used, it is assumed. - or - <expA> array of setup information 10 elements The function requires the user to set certain parameters. These are: a) output to PRINTER or FILE b) WITHOUT or WITH ECHO while printing c) PLAIN or WITH HEADING d) FIRST PAGE EJECT e) FULL REPORT or only SUMMARY All these parameters may already be set by passing the required values together with the reportform name in an array of 10 elements as the parameter. The Setup of this array should be: { <expAC1>,; <expAL1>,; <expAL2>,; <expAL3>,; <expAL4>,; <expAL5>,; <expAL6>,; <expAL7>,; <expAL8>,; <expAL9> } where the single elements represent following: <expAC1> name of report form <expAL1> .T. to Printer, .F. to File, <expAL2> .T. without Screen Echo, .F. with Screen Echo <expAL3> .T. Plain, .F. with Heading <expAL4> .T. first page eject, .F. no first page eject <expAL5> .T. full report, .F. only summary <expAC2> Heading string to be used if <expAL3> is set to .F. (printing with heading). Note: Will be ignored if <expAL3> is set to value .T. [<expAN1>] an optional integer identifying the recordnumber of a single record to be printed. Note: [<expAN2>] will be ignored if anything is in this element. [<expAN2>] an optional integer identifying the next "n" - amount of records to be printed. Note: [<expAN1>] will be ignored if anything is in this element. [<expAL6>] optional logical value to determine if all records are to be processed or only the REST ( from current position to end of file ). .T. if printing the REST, .F. to print all Note: Both [<expAN1>] and [<expAN2>] will be ignored if anything is in this element. Notes: Using only a formname when calling the function has the same result as using a parameter-array with following settings: { "< formname >",; && <- Formname .T.,; && <- output to printer .T.,; && <- no echo .T.,; && <- plain .T.,; && <- eject first page .T.,; && <- full report NIL; && <- heading NIL,; && <- single recordnumber && to print NIL,; && <- next n-records to print .F.,; && <- print all records } Make sure all Elements which are not used contain a NIL value. Examples: proutput( "MYFORM" ) && prints using MYFORM.FRM && and defaults - or - //----------------------------------------------- This array-setup will: a) use form "MYFORM.FRM" b) output to printer c) give no echo to screen d) uses default headings, thus ignoring the header written into element 7. e) eject the first page f) do a FULL report g) output all records in database prnArray := { "MYFORM", && <- Formname .T.,; && <- output to printer .T.,; && <- no echo .T.,; && <- plain .T.,; && <- eject first page .T.,; && <- full report "Headings"; && <- will be ignored this && time!!!! NIL,; && <- single recordnumber && to print NIL,; && <- next n- records to print .F.,; && <- print some or all && records } ) - or - //--------------------------------------------------- This array-setup will: a) use form "MYFORM.FRM" b) output to File. The Function will ask for a filename and will use it as output file. c) give no echo to screen d) uses the header written into element 7. e) eject the first page f) do a FULL report g) output all records in database prnArray := { "MYFORM", && <- Formname .F.,; && <- output to File .T.,; && <- no echo .F.,; && <- with heading .T.,; && <- eject first page .T.,; && <- full report "Headings"; && <- will be used this && time!!!! NIL,; && <- single recordnumber && to print NIL,; && <- next n- records to print .F.,; && <- print some or all && records } ) - or - //----------------------------------------------------- This array-setup will: a) use form "MYFORM.FRM" b) output to printer c) give no echo to screen d) uses default headings, thus ignoring the header written into element 7. e) eject the first page f) do a FULL report g) output ONLY the RECORD 1 as identified. prnArray := { "MYFORM", && <- Formname .T.,; && <- output to printer .T.,; && <- no echo .T.,; && <- plain .T.,; && <- eject first page .T.,; && <- full report "Headings"; && <- will be ignored & this time!!!! 1,; && <- single recordnumber && to print NIL,; && <- next n- records to print .F.,; && <- print some or all && records } ) - or - //------------------------------------------------------- This array-setup will: a) use form "MYFORM.FRM" b) output to printer c) give no echo to screen d) uses default headings, thus ignoring the header written into element 7. e) eject the first page f) do a FULL report g) outputs the NEXT 200 RECORDS prnArray := { "MYFORM", && <- Formname .T.,; && <- output to printer .T.,; && <- no echo .T.,; && <- plain .T.,; && <- eject first page .T.,; && <- full report "Headings"; && <- will be ignored this && time!!!! NIL,; && <- single recordnumber && to print 200,; && <- next n-records to print .F.,; && <- print some or all && records } ) - or - //------------------------------------------------- This array-setup will: a) use form "MYFORM.FRM" b) output to printer c) give no echo to screen d) uses default headings, thus ignoring the header written into element 7. e) eject the first page f) do a FULL report g) output the REST of the records in the Database relative to the recordpointer position. prnArray := { "MYFORM", && <- Formname .T.,; && <- output to printer .T.,; && <- no echo .T.,; && <- plain .T.,; && <- eject first page .T.,; && <- full report "Headings"; && <- will be ignored this && time!!!! NIL,; && <- single recordnumber to print NIL,; && <- next n-records to print .T.,; && <- print the rest } ) proutput( prnArray ) && uses the defined array for parameters Returns: .T. if print was successful; otherwise .F. IMPORTANT STRING FUNCTION INFORMATION ===================================== Although CLIPPER provides String functions I have endeavored to provide You with some functions giving You more control over the handling. Some functions make use of low level C functions for speeding things up. They are however all fully overlayable and are in many ways faster and smaller than the provided CLIPPER string functions. STARRANGE() =========== Function: STARRANGE( <expC>, <expN1>..<expN3> ) --> string Synopsis: Rearranges a string. <expC> string to work on. <expN1> starting position for extract <expN2> length of extract <expN3> new startplace of extract AFTER text was extracted Samples: lString := "WINTERGARDEN" lString := STARRANGE( lString, 7, 6, 1 ) ( returns "GARDENWINTER" ) Returns: altered String STBEGINSWITH() ============== Function: STBEGINSWITH( <expC1>, <expC2> ) --> logical Synopsis: Determines if a string begins with another string <expC1> target string to compare <expC2> source string to compare target string with Examples: lString1 := "MASTERPROGRAM" lString2 := "MASTER" lString2 := "SWITCH" STBEGINSWITH( lString1, lString2 ) returns .T. STBEGINSWITH( lString1, lString3 ) returns .F. Returns: .T. if <expC1> begins with <expC2>, otherwise .F. STCENTER() ========== Function: STCENTER( <expC>, <expN> ) --> string Synopsis: Centers a string within a given length. To do this, the function will first pad the given string to the length required ( set with <expN> ) and centers the passed string ( in <expC> ) with the given length. <expC> the string to be centered. <expN> the length ( width ) in which string is to be centered. Examples: lNewString := STCENTER( "Old String", 20 ) && lNewString is now 20 characters long and centered && result: " Old String " Notes: If <expN> is less than the length of <expC>, the function will return the same string unaltered. Returns: a centered String if successful, the passed string if unsuccessful, NIL if parameters are invalid STCHRINSTR() ============ Function: STCHRINSTR( <expC1>, <expC2> ) --> integer Synopsis: Searches a string for the first occurance of a character and returns its position if found. <expC1> string to be searched <expC2> character to search for Examples: lString := "This is a string" lPos := STCHRINSTR( lString, "a" ) && lPos will contain 9 Returns: an integer showing the position of the found character. STCRUNCH() ========== Function: STCRUNCH( <expC>, <expN> ) --> string Synopsis: Erases spaces contained in a string and appends them to the end of the string. <expC> string to work on <expN> action code as defined in VERTEXUS.CH: MOVE_ALL = moves all spaces to end of string MOVE_NO_SINGLE = moves all but single spaces to end of string Examples: lString1 := "MOEVENPICK Ice Cream" STCRUNCH( lString1, MOVE_NO_SINGLE ) && returns "MOEVENPICK Ice Cream " - or - STCRUNCH( lString1, MOVE_ALL ) && returns "MOEVENPICKIceCream " Returns: crunched string depending upon action, NIL if wrong parameters passed STCUTLEFT() =========== Function: stcutleft( <expC1>, <expN1> ) --> string Synopsis: The function is cutting off the left side of a given string the amount of characters passed in <expN1>. <expC1> the string to cut <expN1> the amount of characters to cut off Examples: lString := "A very long string we have!" lString := STCITLEFT( lString, 7 ) && lString = "long string we have!" Returns: remaining string STCUTRIGHT() ============ Function: stcutright( <expC1>, <expN1> ) --> string Synopsis: The function is cutting off the right side of a given string the amount of characters passed in <expN1>. <expC1> the string to cut <expN1> the amount of characters to cut off Examples: lString := "A very long string we have!" lString := STCUTRIGHT( lString, 9 ) && lString = "A very long string" Returns: remaining string STENDSWITH() ============ Function: STENDSWITH( <expC1>, <expC2> ) --> logical Synopsis: Determines if a string ends with another string <expC1> target string to compare <expC2> source string to compare target string with Examples: lString1 := "MASTERPROGRAM" lString2 := "PROGRAM" lString2 := "SWITCH" STENDSWITH( lString1, lString2 ) returns .T. STENDSWITH( lString1, lString3 ) returns .F. Returns: .T. if <expC1> ends with <expC2>, otherwise .F. STLPAD() ======== Function: STLPAD( <expC>, <expN> ) --> string Synopsis: Pads a string with spaces at left side of string <expC> string to pad <expN> new length of string Notes: string will be truncated if <expN> is smaller than original string length. Returns: string left padded with spaces. STLSHIFT() ========== Function: STLSHIFT( <expC>, <expN> ) --> string Synopsis: Shift a string to left side. All leftmost characters are lost. <expC> string to shift <expN> number of positions to shift left Returns: string as remained after left-shift STRPAD() ======== Function: STRPAD( <expC>, <expN> ) --> string Synopsis: Pads a string with spaces at right side of string <expC> string to pad <expN> new length of string Notes: string will be truncated if <expN> is smaller than original string length. Returns: string right padded with spaces. STRSHIFT() ========== Function: STRSHIFT( <expC>, <expN> ) --> string Synopsis: Shift a string to right side. All rightmost characters are lost. <expC> string to shift <expN> number of positions to shift right Returns: string as remained after right-shift IMPORTANT SYSTEM FUNCTION INFORMATION ===================================== All System functions are low level C and Assembler functions. They are all well behaved and written in Microsoft C 6.00 and Turbo Assembler 1.0 I have sofar not experienced any problems with them and they should not give You any either. Never the less, since they go into the Hart of the Computer You should use them cautiously and strictly the way suggested in the descriptions. To speed things, I have ommitted any param checking in these functions as it is assumed You know what You are doing. SYCHDIR() ========= Function: SYCHDIR( <expC1> ) --> integer Synopsis: Changes the current directory. <expC1> the path where to change to. Returns: 0 if change occurred an integer < 0 on error SYCHDRIVE() =========== Function: SYCHDRIVE( <expC1>|<expN1> ) --> logical Synopsis: changes the standard drive. <expC1> a character identifying the drive to change to <expN1> a number identifying the drivenumber to change to the number represents the drive as identified by DOS. Returns: .T. if successful .F. on error SYCOLDBOOT() ============ Function: SYCOLDBOOT() --> NIL Synopsis: Reboots the system (includes a RAM-Check ) Returns: nothing SYCURDRV() ========== Function: SYCURDRV() --> integer Synopsis: Returns the current Drivenumber. The function checks the system and returns the current drive in form of a number ( 1 = A, 2 = B, 3 = C, ... etc. ) Returns: an integer identifying the current drive. SYDRVEFREE() ============ Function: SYDRVEFREE( <expN1>|<expC1> ) --> integer Synopsis: Checks a drive and returns the free Diskspace. <expN1>| <expC1> the identifier of the drive to be checked if a number is passed it will represent the drive according to the DOS calling convention Returns: a long integer representing the free diskspace available. SYDRIVE() ========= Function: SYDRIVE() --> character Synopsis: Returns the current Drive. The function is calling the C-Function SYCURDRV() to convert the drivenumber returned by the C-Function into the equivalent Character value. Returns: a character identifying the current drive. SYDRIVES() ========== Function: SYDRIVES() --> string Synopsis: Get available drives of system an returns these in a string. Return: string of available drives SYDRVETTL() =========== Function: SYDRVETTL( <expN1>|<expC1> ) --> integer Synopsis: Checks a drive and returns the total Diskspace. <expN1>| <expC1> the identifier of the drive to be checked if a number is passed it will represent the drive according to the DOS calling convention Returns: a long integer representing the total diskspace available. SYDRVROK() ========== Function: SYDRVRDOK( <expC1>|<expN1> ) --> logical Synopsis: Check if the drive, identified by the parameter is ready to read or not. Examples: IF SYDRVRDOK( "A" ) .... your code to read from disk ... ELSE .... other action since drive is not ready .... ENDIF Returns: .T. if drive is ready, otherwise .F. SYDRVWOK() ========== Function: SYDRVWRTOK( <expC1>|<expN1> ) --> logical Synopsis: Check if the drive, identified by the parameter is ready to write or not. Examples: IF SYDRVWRTOK( "A" ) .... your code to write to disk ... ELSE .... other action since drive is not ready .... ENDIF Returns: .T. if drive is ready, otherwise .F. SYMKDIR() ========= Function: SYMKDIR( <expC1> ) --> integer Synopsis: Creates a subdirectory. <expC1> is string naming the new subdirectory Notes: <expC1> should be a string such as You would use when creating a subdirectory in the DOS environment with the DOS command "MD" or "MKDIR". Returns: 0 if subdirectory created succesfully, any number less than 0 on error. SYRMDIR() ========= Function: SYRMDIR( <expC1> ) --> integer Synopsis: Erases the subdirectory passed as parameter. <expC1> the subdirectory to be erased. Notes: The subdirectory to be erased must be empty. Returns: 0 if erased correctly; an integer < 0 on error IMPORTANT GENERAL FUNCTIONS INFORMATION ======================================= In this category I have included all functions for which I have not established a group. You may find some functions in here provided by someone else I have included them here simply because they are good and complement the CLIPPER library in many ways. These functions were all distributed inclusive Source code, and I have included the source code on the disk for Your usage. Wherever I used someone elses function, I have made mentioning of it. I do not want to have any credit for it, nor do I want to make anything out of it. I simply use them and provide them to You for Your benefit. UTBITSET() ========== Function: UTBITSET( <expC1>, <expN1> ) --> character Synopsis: Sets a selected bit in a BYTE (character) <expC1> character (BYTE) to set a bit in <expN1> bitposition to set ( 0 - 7, right to left ) In effect, ORs argument byte with a byte that has only the target bit set. If bit is already set, it remains set. Examples: Newbyte := UTBITSET( CHR(107), 4 ) ? ASC( Newbyte ) // result: 123 ? Newbyte // result: '{' Returns: New byte (character) , with designated bit set. If parameters are faulty, returns NIL. UTBELLATTN() ============ Function: UtBellAttn() --> NIL Synopsis: a single tone at 200 Hz for the duration of 1/18th of a second and 100 Hz for the same duration. Note: The tone sounds only if the global variable _quiet is set to .F. Returns: nothing UTBELLERROR() ============= Function: UtBellError() --> NIL Synopsis: a single tone at 100 Hz for the duration of 2/18th of a second. Note: The tone sounds only if the global variable _quiet is set to .F. Returns: nothing UTBELLDONE() ============ Function: UtBellDone() --> NIL Synopsis: a single tone at 500 Hz for the duration of 1/18th of a second. Note: The tone sounds only if the global variable _quiet is set to .F. Returns: nothing UTBELLUDF() =========== Function: UtBellUdf( <expA1> ) --> NIL Synopsis: a single tone or a combination of tones depending upon the values passed. <expA1> a 2-dim. array containing one or more tones. The array should be created in following fashion: { { <frequency>,... }, { <duration>,... } } Examples: To have the same effect with UtBellUdf() as with UtBellAttn() create an array like: AttnTone := { { 200, 100 }, { 1, 1 } } and call the function like: UtBellUdf( Attntone ) Note: The tone sounds only if the global variable _quiet is set to .F. Returns: nothing UTBYTEAND() =========== Function: UTBYTEAND( <expC1>, <expC2> ) --> character Synopsis: Performs bit-wise AND on two BYTES (characters) <expC1> BYTE to be AND'ed <expC2> to AND <expC1> with <expC1> and <expC2> are characters from CHR(0) TO CHR(255). May be passed in CHR() form, as character literals, or as expressions evaluating to CHR() values. Can be used for any bit-wise masking operation. In effect, this is a bit-by-bit AND operation. Equivalent to AND assembler instruction. Returns: resulting byte, in CHR() form. If parameters are faulty, returns NIL. UTBYTEOR() ========== Function: UTBYTEOR( <expC1>, <expC2> ) --> character Synopsis: Performs bit-wise OR on two characters. <expC1> the character to be OR'd <expC2> the character to OR with <expC1> and <expC2> are characters from CHR(0) TO CHR(255). May be passed in CHR() form, as character literals, or as expressions evaluating to CHR() values. Examples: This code performs a bit-wise OR on two bytes represented by CHR(20) and CHR(10): NewChar := UTBYTEOR( CHR(20), CHR(10) ) ? ASC( NewChar ) // result: 30 ? NewChar // result: non-printable character Returns: character in CHR() form. If parameters are faulty, returns NIL. UTCHKCURSTYPE() =============== Function: UtChkCursType( <expN> ) --> logical value Synopsis: accepts a numerical value representing the cursortype defined in CLIPPER for user with the SETCURSOR() function <expN> numerical expression as defined in SETCURS.CH Returns: .T. if numerical expression identifies valid cursorshape .F. if numerical expression out of bounds or expression invalid. UTCOLCONVERT() ============== Function: UTCOLCONVERT( <expC1>, <expN1> ) --> integer Synopsis: returns a color integer for colorsetting You have Your colorstring but need the reference color integer. <expC1> colorstring to convert <expN1> what part of colorstring to retrieve as integer identified as: 0 = foreground standard 1 = background standard 2 = standard colorsetting 3 = foreground enhanced 4 = background enhanced 5 = enhanced colorsetting Examples: lColor := UTCOLCONVERT( SETCOLOR(), 2 ) && returns standard && color integer lColor := UTCOLCONVERT( SETCOLOR(), 2 )+128 && returns standard && color integer && and sets the blink && attribute lColor := UTCOLCONVERT( "W/N", 1 ) && returns background Returns: Integer representing the CLIPPER color number. UTCTRLW() ========= Function: UTCTRLW() Synopsis: Sends a CONTROL-W ( CHR(23) ) to the keyboard. Allows remapping of a key to Ctrl-W Examples: SET KEY F10 to UTCTRLW && sends CTRL-W to keyboard whenever F10 is pressed Returns: Nothing UTGETCURSTYPE() =============== Function: UtGetCursType( [<expN1> .. <expN4>], [<expC>], [<expN5>] ) --> integer Synopsis: Pops up a window of selection of available cursor types. Call this function: cursshape := UtGetCursType() SETCURSOR( cursshape ) [<expN1>..<expN4>] optional window coordinates defaults to screen center. [<expC>] optional box Colorstring defaults to c_popcol [<expN5>] optional boxshadow position defaults to c_shadpos if no coordinates are given, the window is popped up in the center of the screen with default colors. Returns: an Integer denoting the cursorshape to be used with the CLIPPER function SETCURSOR(). If no cursorshape was selected the function returns the currents cursor shape. UTDRIVES() ========== Function: UTDRIVES() --> string Synopsis: Checks the Computer System for available drives and returns info as string. Examples: lString := UTDRIVES() && lString may contain "ABC" && if computer has 2 Floppies and 1 HD Notes: virtual disks will be reportet as well This Function is a C-Function. UTEDPIC() ========= Function: Utedpic( <expC1>, <expN1>, <expN2>, [<expC2>] ) --> PICTURE Synopsis: Returns a picture clause appropriate for editing field <expC1> is the value of the field or variable. <expN1> denotes LEFTMOST COLUMN where GET is displayed. <expN2> denotes RIGHTMOST COLUMN where GET is displayed. [<expC2>] allows optionally passing of userdefined PICTURE. Notes: Checks if RIGHTMOST column lies within Screen Boundaries and adjusts the column to POSSIBLE RIGHTMOST COLUMN - 2 if only the first 3 parameters are passed. Boundary checks are not done if [<expC2>] is passed as it is assumed that user knows what he is doing. If Utedpic is used on Numeric fields, make sure that overall fieldlength does not exceed 15 positions EXLUSIVE the signs -+.() as they are counted as positions as well by CLIPPER, otherwise the number may not be displayed and Your will see the whole field displayed in default width filled with "*". Can't do anything about this ( at least have not found a way around it ) as it seems to be CLIPPER's own decision to do this. Example: @10,10 GET FIRSTNAME PICTURE UTEDPIC( @FIRSTNAME,; 10, 20 ) && would return a picture of "@KSXXXXXXXXXX" Returns: Picture - description UTENHANCED() ============ Function: UTENHANCED() --> integer Synopsis: returns a color integer for enhanced setting used for functions that require it like ATT() and PRNT() Examples: lColor := UTENHANCED() && returns enhanced color integer PRNT(10,10,"Waiting...!",lColor ) Returns: Integer representing the CLIPPER color number. UTERRFUNCTION() =============== Function: UtErrFunction( <expO> ) --> NIL Synopsis: The VERTEX Error handling function. Handles various kinds of errors and informs the user of the kind of error happening. Gives the user then a choice of actions which will be stored in the ErrorObject:cargo slot for further action. Although no value is being returned, You are able to use the ErrorObject for Your RECOVERY. Several possible errors are being directly treated: 1) opening a Database 2) opening an Index 3) DOS file open error 4) DOS file close error 5) File corruption error E.g. You allow the user to open some file for usage but You cant be sure that the user opens a DBase Type file for reading. This would result in a fatal error crashing Your program. To have a chance to continue anyway (i.e. allow the user to reselect a file ) do the following: a) set up Your own error handle b) allow the user to select the database c) open the database while using the statement BEGIN SEQUENCE ... RECOVER USING ... END d) test ErrorObject:cargo if recover is wanted. Examples: LOCALlObjLocal,; && contains the ErrorObject lSelFile,; && contains selected filename lSuccess := .T. && set to false if file is bad && install Errorfunction lLastHandle := ERRORBLOCK( { | FileobjErr |; UtErrFunction( FileobjErr ) } ) DO WHILE .T. .... allow the user to select a file ..... BEGIN SEQUENCE USE ( lSelFile ) NEW && use the selected file RECOVER USING lObjLocal && the ErrorObject will be && used here... Remember that && the CARGO slot will contain && a .T. or .F. value && depending && on the action the user && wants to do since && his action failed. IF ErrorObject:cargo LOOP ELSE lSuccess := .F. EXIT ENDIF END END Returns: Nothing UTEXPRISTRUE() ============== Function: UtExpristrue( <expC> ) --> logical Synopsis: Evaluates an expression used against a Database record. Used by CLIPPER function DBEVAL() in second codeblock parameter if the expression is stored in a variable. E.g.: lExpr := "SOUNDEX(FIELDGET(1)) = SOUNDEX("MASTERS")" To use DBEVAL() correctly by using a variable as FOR or WHILE condition in the respective codeblock, the expression must be used as a MACRO to be evaluated to a LOGICAL value. E.g.: DBEVAL( {|| <dowhatever if TRUE> }, {|| &lExpr } ). To use an expression together with a macro in the second codeblock, we have to call the UtExpristrue() function and pass the expression to it for evaluation. E.g.: DBEVAL({||...},{||firstfunc(),UtExpristrue(lExpr)}) This runs the DBEVAL() function correctly. Note: If you want to use this Expression Evaluation Function, make sure it is called LAST within the second codeblock of the DBEVAL() function or things wont work. No Typechecking is done to ensure maximum speed so make sure you pass a valid expression. Best use the function MfMakeExpr() to create interactively a VALID expression. Returns: .T. if expression evaluates to .T. otherwise .F. UTSAVEKEY() =========== Function: UtSaveKey( <expL> ) --> NIL Synopsis: Saves and restores SET KEYS of F1 to F10 key If you call this function, it will save or recall SET KEYS depending upon the parameter passed. This enables you to re-assign SET KEYS to functions after you have called this function and RE-set the keys afterwards to their original settings. Examples: SET KEY K_F1 to Help && sets F1 to Help() function UtSaveKey( .T. ) && save the setting SET KEY K_F1 to OtherHelp && sets F1 to OtherHelp() function UtSaveKey( .F. ) && resets F1 to Help() function Notes: Don't call the UtSaveKey() function twice in a row with the parameter .T. or the first saved functionkey setting are being lost. e.g. SET KEY K_F1 to Help UtSaveKey( .T. ) UtSaveKey( .T. ) <-- all settings are lost at this point Returns: 0 if call was unsuccessful 1 if functions are saved -1 if functions are restored UTINIT() ======== Function: UTINIT() --> NIL Synopsis: Initializes the global variables expected by functions located in the Library if they are not already present. It will also look for a variable called _SETISCOLOR. If it is present and of type "L", its value will be used in place of ISCOLOR(). You may want to initialize a public variable _SETISCOLOR if you have one of those card/monitor combos that fool ISCOLOR(). UTINIT() will also check Your system for the presence of a graphics adapter and set the graphics GLOBALS to the highest possible value in sequence of: CGA EGA VGA resolutions. If You have a graphics adapter with different resolutions than the standard listed above, You may use the function GRINIT() to set the maximal X,Y coordinates for Your system. Examples: at beginning of top level program... UTINIT() Notes: Its always a good idea to call this at your top level program. All of the functions doing screen i/o call it. It initializes the global variable _CLIPFUNC the first time it is called. Returns: Nothing UTISBIT() ========= Function: UTISBIT( <expC1>, <expN1> ) --> logical Synopsis: Test bitstatus of bits in a BYTE (character) <expC1> BYTE or character to examine <expN1> Bitposition to examine (0 - 7, right to left ) i.e. 0 is equal to rightmost bit, 7 is equal to leftmost bit. Checks the identified Bit position in a given Byte for the status of the identified Bit. Examples: lBitflag := UTISBIT(CHR(65), 7) ? lBitflag// result: .T. ? UTISBIT('A', 5) // result: .F. Returns: .T. if designated bit is set, .F. if bit is not set, otherwise NIL UTKEEPVAR() =========== Function: UtKeepVar( <expC1> ) --> Filename Synopsis: Writes <expC1> to disk and returns a unique Filename. <expC1> a string of any kind. This Function is very useful in writing saved screen variables to disk for keeping them there for the duration of the program so they may be recalled at a later time. Allows saving quite some Memory. MEMO Fields may be exported into a file for editing with an external editor. Just remember to erase the Files. Do this by using the function uttempclean() as last functioncall in your program: Examples: lScrSave := SAVESCREEN( 0,0,20,50 ) lFilename := UtKeepVar( lScrSave ) && lFilename contains a unique filename where the SAVESCREEN && string was written to... - or - lFilename := UtKeepVar("this string is written to disk") Returns: Filename if successfully saved, otherwise empty string UTPROFILE() =========== Function: utprofile() Synopsis: This is a Clipper 5.01 specific re-write of the profiler included with Blinker 1.5x (originally written and donated by Frederick W. Stangl, President of Dynamic Performance Inc., Philadelphia, PA). This version of the profiler was written by Todd C. MacDonald, Senior Programmer/Analyst of Key Services Corporation, Albany, NY, and is also donated to the Blinker community. This version takes advantage of 5.01's nested arrays to allow viewing of the profiling statistics in any user-selectable order. To invoke the profiler from any wait-state, press [Alt]-[P]. I found this modul so good, I included in the library for development purposes. The source-code may be ordered by sending me a SAE together with US $ 10.00 for postage and handling and I will provide You with the source on disk; the code is also available on several good Bulletin Boards and via COMPUSERVE in the Nantucket User Forum. UTSTANDARD() ============ Function: UTSTANDARD() --> integer Synopsis: returns a color integer for standard setting used for functions that require it like VIATT() and VIPRNT() The functions writes the string direct to VIDEO MEMORY and is thus VERY FAST!!! However it doesn't work in all modes (some graphics modes ). It works with all video modes using either B000h or B800h as base address ( e.g. EGA, VGA etc. ) Examples: lColor := UTSTANDARD() && returns standard && color integer lColor := UTSTANDARD()+128 && returns standard && color integer && and sets the blink && attribute VIPRNT(10,10,"Waiting...!",lColor ) Returns: Integer representing the CLIPPER color number. UTUNSELECTED() ============== Function: UTUNSELECTED() --> integer Synopsis: Returns a color integer for UNSELECTED setting used by functions ATT() and PRNT() Returns: numeric color integer IMPORTANT VIDEO FUNCTION INFORMATION ==================================== I have put together a host of videofunctions which are supposed to help in writing applications which use the peculiarities of the Video Cards ( VGA, XVGA etc. ) You can buy nowadays and give You the chance of using higher resolutions and thus more info on the screen. The provided Videofunctions are all written in Assembler language and provide direct access to Video Card interrupts. The functions will make use of documented features of the video cards and should therefore work for all video cards that are able to support the screen modes the functions will try to switch to. The general videofunctions will use the INT10h BIOS call to switch modes. Following modes are being used: 00h - 13h The documentation to these modes You may find in the Microsoft Press series of books. Before You use any of these general videofunctions make sure that the installed videocard can make use of the requested modes. Using the general function whilst having a videocard installed that does not support the requested modes may however result in the worst case in a System-Lockup ( generally the functions simply don't work ). Be aware though that Your Video Card MUST support the display mode You try to select. Usually the functions just don't do anything however in some extreme rare cases You may hang the System. So use the functions wisely. VIATT() ======= Function: VIATT( <expN1> .. <expN5>, [<expC1>] ) --> NIL Synopsis: Change attribute of area of the screen <expN1>..<expN4> screen coordinates to change attributes ( top, left, bottom, right ) <expN5> new attribute to set area to <expC1> optional character to fill area with The functions writes the string direct to VIDEO MEMORY and is thus VERY FAST!!! However it doesn't work in all modes (some graphics modes ). It works with all video modes using either B000h or B800h as base address ( e.g. EGA, VGA etc. ) Examples: VIATT( 10,10,20,60,16,"+" ) Returns : nothing. VICLS() ======= Function: VICLS( [<expN>], [<expC>] ) --> NIL Synopsis: Clears the current screen with optional color and character [<expN>] an optional color-number which is used to clear the current screen [<expC>] an optional character which is used. This is a low level function to clear the screen and does not depend upon the CLIPPER color scheme. The numeric color code however is the same that CLIPPER supports sofar. Examples: VICLS() && clear screen with && current color VICLS( 48 ) && clear screen black && on cyan VICLS( 48, CHR( 176 ) ) && clear screen && black on cyan with && character "+" Returns: Nothing VICOLGRID() =========== Function: VICOLGRID( <expN1>, <expN2> ) Synopsis: Draws colored blocks in SETCOLORS() function <expN1> top row coordinate <expN2> top left coordinate The function will draw a number of blocks on the screen in SETCOLOR() attributes. Used by MFSETCOLOR() function Returns: Nothing VIFADE() ======== Function: VIFADE(<expN1>..<expN4>,<expC1>,<expN5>) --> NIL Synopsis: Fades a screen variable off the screen <expN1> .. <expN4> screen coordinates <expC1> screen variable to fade off the screen <expN5> time delay to use ( 0 - 20 ) Returns: Nothing VIGETMODE() =========== Function: VIGETMODE() --> array Synopsis: Returns Video System Info The function will post Video System information into an array 5 elements long with following information: array[1] hex string of current screen mode array[2] available columns ( integer ) array[3] available rows ( integer ) array[4] current page ( integer ) array[5] 0 for MONO, 1 for COLOR adapter Examples: lArray := VIGETMODE() Returns: array if called successfully, otherwise NIL VIISCGA() ========= Function: VIISCGA() --> logical Synopsis: Checks if active Display is in CGA mode. Returns: .T. active Display Adapter is in CGA mode; otherwise .F. VIISEGA() ========= Function: VIISEGA() --> logical Synopsis: Checks if active Display is in EGA mode. Returns: .T. active Display Adapter is in EGA mode; otherwise .F. VIISHERC() ========== Function: VIISHERC() --> logical Synopsis: Checks if active Display is in HERCULES mode. Returns: .T. active Display Adapter is in HERCULES mode otherwise .F. VIISMCGA() ========== Function: VIISMCGA() --> logical Synopsis: Checks if active Display is in MCGA mode. Returns: .T. active Display Adapter is in MCGA mode otherwise .F. VIISMDA() ========= Function: VIISMDA() --> logical Synopsis: Checks if active Display is in MDA mode Returns: .T. active Display Adapter is in MDA mode otherwise .F. VIISVGA() ========= Function: VIISVGA() --> logical Synopsis: Checks if active Display is in VGA mode Returns: .T. active Display Adapter is in VGA mode otherwise .F. VIPRNT() ======== Function: VIPRNT(<expN1>,<expN2>,<expC1>,<expN3>) --> NIL Synopsis: Write string to row/col with attribute <expN1> - row <expN2> - col <expC1> - String to write <expN3> - color attribute of string The functions writes the string direct to VIDEO MEMORY and is thus VERY FAST!!! However it doesn't work in all modes (some graphics modes ). It works with all video modes using either B000h or B800h as base address ( e.g. EGA, VGA etc. ) Examples: ViPrnt(10,10,"Hello World",23) Notes: Does not change cursor location or color setting. Returns: nothing. VISETMODE() =========== Function: VISETMODE( <expC1> ) --> logical Synopsis: Sets a video card to specified Mode <expC1> numeric value (in HEXADECIMAL notation) representing Mode to set Video card to This function is an all around video set function. It can set a videocard to ANY mode provided it supports it. If You use this function, first of all make sure that Your MONITOR supports the new resolution as some are so high in their display resolution that they may damage Your monitor if they are not supported. PLEASE REFER TO YOUR MONITOR AND VIDEO CARD MANUAL FOR FURTHER INFORMATION IF BOTH SUPPORT THE TYPE OF DISPLAY MODE YOU DESIRE TO SELECT!!! Watch out for the resolutions only supported by MULTISYNC or MULTIFREQUENCY monitors ( they are generally the high HEX numbers > 20 ) However take care in selecting a mode that works fine with Your system. Examples: VISETMODE( "7" ) && sets VGA videocard to && mode 07h VISETMODE( "29" ) && sets VGA card with && ET4000 && into 800x600 graphics mode VISETMODE( "53" ) && sets VGA card with && TVGA 8900 && into 132x25 textmode Returns: .T. if called successfully, otherwise .F. VISLIDEOFF() ============ Function: VISLIDEOFF( ) --> NIL Synopsis: Slides a screen variable off the screen <expN1> .. <expN4> Screen coordinates to slide off <expC1> variable containing the saved screen <expN5> speed of slide..........> The function will slide a saved screen area off the screen. Use a function that saves the screen area first. Then use the slider.... Returns: Nothing